@wordpress/ui 0.8.0 → 0.9.0

package/src/link/style.module.css

@@ -0,0 +1,68 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.link {
+		text-underline-offset: 0.2em;
+		text-decoration-thickness: 0.5px;
+	}
+
+	/* Brand tone */
+	.is-brand,
+	.is-brand:visited {
+		color: var(--wpds-color-fg-interactive-brand);
+	}
+
+	.is-brand:hover,
+	.is-brand:active {
+		color: var(--wpds-color-fg-interactive-brand-active);
+	}
+
+	/* Neutral tone */
+	.is-neutral,
+	.is-neutral:visited {
+		color: var(--wpds-color-fg-interactive-neutral);
+		text-decoration-color: var(--wpds-color-stroke-interactive-neutral);
+	}
+
+	.is-neutral:hover,
+	.is-neutral:active {
+		color: var(--wpds-color-fg-interactive-neutral-active);
+	}
+
+	/* Unstyled variant */
+	.is-unstyled {
+		color: inherit;
+		text-decoration: none;
+	}
+
+	/* Link icon pattern — arrow rendered via ::after pseudo-element to avoid
+	 * Twemoji replacement and text-selection issues. Root <a> gets
+	 * text-decoration:none; the link-contents span re-applies it.
+	 * text-underline-offset is inherited and propagates from .link
+	 * automatically. text-decoration-thickness and text-decoration-color
+	 * are NOT inherited, so they are explicitly redeclared on
+	 * .link-contents (the latter via `inherit` to carry the neutral
+	 * tone's custom color token through). */
+	.has-link-icon {
+		text-decoration: none;
+	}
+
+	.link-contents {
+		text-decoration: underline;
+		text-decoration-color: inherit;
+		text-decoration-thickness: 0.5px;
+	}
+
+	.link-icon {
+		margin-inline-start: var(--wpds-dimension-padding-xs);
+		font-weight: var(--wpds-font-weight-regular);
+	}
+
+	.link-icon::after {
+		content: "\2197";
+	}
+
+	.link-icon:dir(rtl)::after {
+		content: "\2196";
+	}
+}

package/src/link/test/index.test.tsx

@@ -0,0 +1,93 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createRef } from '@wordpress/element';
+import { Link } from '../index';
+
+describe( 'Link', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLAnchorElement >();
+
+		render(
+			<Link ref={ ref } href="/">
+				Home
+			</Link>
+		);
+
+		expect( ref.current ).toBeInstanceOf( HTMLAnchorElement );
+	} );
+
+	describe( 'openInNewTab', () => {
+		it( 'sets target="_blank" when true', () => {
+			render(
+				<Link href="https://example.com" openInNewTab>
+					External
+				</Link>
+			);
+
+			expect( screen.getByRole( 'link' ) ).toHaveAttribute(
+				'target',
+				'_blank'
+			);
+		} );
+
+		it( 'does not set target="_blank" when false', () => {
+			render( <Link href="https://example.com">External</Link> );
+
+			expect( screen.getByRole( 'link' ) ).not.toHaveAttribute(
+				'target'
+			);
+		} );
+
+		it( 'renders an accessible arrow indicator', () => {
+			render(
+				<Link href="https://example.com" openInNewTab>
+					External
+				</Link>
+			);
+
+			expect(
+				screen.getByLabelText( '(opens in a new tab)' )
+			).toBeInTheDocument();
+		} );
+
+		it( 'prevents default for internal anchor links', async () => {
+			const user = userEvent.setup();
+			const onClick = jest.fn();
+
+			render(
+				<Link href="#section" openInNewTab onClick={ onClick }>
+					Jump
+				</Link>
+			);
+
+			await user.click( screen.getByRole( 'link' ) );
+
+			expect( onClick ).toHaveBeenCalledTimes( 1 );
+			expect( onClick.mock.calls[ 0 ][ 0 ].defaultPrevented ).toBe(
+				true
+			);
+		} );
+
+		it( 'does not prevent default for external links', async () => {
+			const user = userEvent.setup();
+			const onClick = jest.fn();
+
+			render(
+				<Link
+					href="https://example.com"
+					openInNewTab
+					onClick={ onClick }
+				>
+					External
+				</Link>
+			);
+
+			await user.click( screen.getByRole( 'link' ) );
+
+			expect( onClick ).toHaveBeenCalledTimes( 1 );
+			expect( onClick.mock.calls[ 0 ][ 0 ].defaultPrevented ).toBe(
+				false
+			);
+		} );
+	} );
+} );

package/src/link/types.ts

@@ -0,0 +1,36 @@
+import { type ReactNode } from 'react';
+import { type ComponentProps } from '../utils/types';
+
+export interface LinkProps extends Omit< ComponentProps< 'a' >, 'target' > {
+	/**
+	 * The visual treatment of the link.
+	 *
+	 * - `default`: Applies tone-based color and underline styles.
+	 * - `unstyled`: Strips all visual styles so consumers can bring their own.
+	 *
+	 * @default "default"
+	 */
+	variant?: 'default' | 'unstyled';
+
+	/**
+	 * The tone of the link. Tone describes a semantic color intent.
+	 * Only applies when `variant` is `default`.
+	 *
+	 * @default "brand"
+	 */
+	tone?: 'brand' | 'neutral';
+
+	/**
+	 * Whether to open the link in a new browser tab.
+	 * When true, sets `target="_blank"`, appends a visual arrow indicator,
+	 * and prevents navigation for internal anchors (`#`-prefixed hrefs).
+	 *
+	 * @default false
+	 */
+	openInNewTab?: boolean;
+
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}

package/src/notice/action-link.tsx

@@ -1,28 +1,22 @@
-import { forwardRef } from '@wordpress/element';
-import { useRender, mergeProps } from '@base-ui/react';
 import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { Link } from '../link';
 import type { ActionLinkProps } from './types';
 import styles from './style.module.css';
 
 /**
  * An action link for use within Notice.Actions.
- *
- * TODO: This should use a shared Link component.
  */
 export const ActionLink = forwardRef< HTMLAnchorElement, ActionLinkProps >(
-	function NoticeActionLink( { className, render, ...props }, ref ) {
-		const element = useRender( {
-			defaultTagName: 'a',
-			render,
-			ref,
-			props: mergeProps< 'a' >(
-				{
-					className: clsx( styles[ 'action-link' ], className ),
-				},
-				props
-			),
-		} );
-
-		return element;
+	function NoticeActionLink( { className, ...props }, ref ) {
+		return (
+			<Link
+				ref={ ref }
+				className={ clsx( styles[ 'action-link' ], className ) }
+				{ ...props }
+				tone="neutral"
+				variant="default"
+			/>
+		);
 	}
 );

package/src/notice/description.tsx

@@ -1,23 +1,21 @@
 import { forwardRef } from '@wordpress/element';
-import { useRender, mergeProps } from '@base-ui/react';
+import clsx from 'clsx';
 import type { DescriptionProps } from './types';
+import { Text } from '../text';
 import styles from './style.module.css';
 
 /**
  * The description text for a notice.
  */
-export const Description = forwardRef< HTMLDivElement, DescriptionProps >(
-	function NoticeDescription( { render, ...props }, ref ) {
-		const element = useRender( {
-			defaultTagName: 'div',
-			render,
-			ref,
-			props: mergeProps< 'div' >(
-				{ className: styles.description },
-				props
-			),
-		} );
-
-		return element;
+export const Description = forwardRef< HTMLSpanElement, DescriptionProps >(
+	function NoticeDescription( { className, ...props }, ref ) {
+		return (
+			<Text
+				ref={ ref }
+				variant="body-md"
+				className={ clsx( styles.description, className ) }
+				{ ...props }
+			/>
+		);
 	}
 );

package/src/notice/style.module.css

@@ -10,6 +10,7 @@
 		--wp-ui-notice-text-color: var(--wpds-color-fg-content-neutral);
 		--wp-ui-notice-decorative-icon-color: var(--wpds-color-fg-content-neutral);
 
+		container-type: inline-size;
 		display: grid;
 		align-items: start;
 		grid-template-columns: auto 1fr auto;
@@ -31,10 +32,6 @@
 
 		padding-block: var(--text-vertical-padding);
 
-		font-family: var(--wpds-font-family-heading);
-		font-size: var(--wpds-font-size-md);
-		font-weight: var(--wpds-font-weight-medium);
-		line-height: var(--wpds-font-line-height-sm);
 		color: var(--wp-ui-notice-text-color);
 	}
 
@@ -43,10 +40,6 @@
 
 		padding-block: var(--text-vertical-padding);
 
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-md);
-		font-weight: var(--wpds-font-weight-regular);
-		line-height: var(--wpds-font-line-height-sm);
 		text-wrap: pretty;
 		color: var(--wp-ui-notice-text-color);
 	}
@@ -76,20 +69,6 @@
 		font-weight: var(--wpds-font-weight-regular);
 		line-height: var(--wpds-font-line-height-sm);
 		margin-block: auto;
-		text-underline-offset: 0.2em;
-		text-decoration-thickness: 0.5px;
-		color: var(--wpds-color-fg-interactive-neutral);
-		text-decoration-color: var(--wpds-color-stroke-interactive-neutral);
-
-		&:visited {
-			color: var(--wpds-color-fg-interactive-neutral);
-			text-decoration-color: var(--wpds-color-stroke-interactive-neutral);
-		}
-
-		&:hover,
-		&:active {
-			color: var(--wpds-color-fg-interactive-neutral-active);
-		}
 
 		/* Add more horizontal space when following another action link/button */
 		&:not(:first-child) {
@@ -135,6 +114,14 @@
 		--wp-ui-notice-text-color: var(--wpds-color-fg-content-error);
 		--wp-ui-notice-decorative-icon-color: var(--wpds-color-fg-content-error-weak);
 	}
+
+	/* Matches --wpds-dimension-surface-width-sm (container queries don't support custom properties). */
+	@container (max-width: 320px) {
+		.notice:has(.title) .description,
+		.notice:has(.title) .actions {
+			grid-column: 1 / 3;
+		}
+	}
 }
 
 @layer wp-ui-compositions {

package/src/notice/test/index.test.tsx

@@ -8,7 +8,7 @@ describe( 'Notice', () => {
 		it( 'forwards ref', () => {
 			const rootRef = createRef< HTMLDivElement >();
 			const titleRef = createRef< HTMLSpanElement >();
-			const descriptionRef = createRef< HTMLDivElement >();
+			const descriptionRef = createRef< HTMLSpanElement >();
 			const actionsRef = createRef< HTMLDivElement >();
 			const actionButtonRef = createRef< HTMLButtonElement >();
 			const actionLinkRef = createRef< HTMLAnchorElement >();
@@ -36,7 +36,7 @@ describe( 'Notice', () => {
 			);
 			expect( rootRef.current ).toBeInstanceOf( HTMLDivElement );
 			expect( titleRef.current ).toBeInstanceOf( HTMLSpanElement );
-			expect( descriptionRef.current ).toBeInstanceOf( HTMLDivElement );
+			expect( descriptionRef.current ).toBeInstanceOf( HTMLSpanElement );
 			expect( actionsRef.current ).toBeInstanceOf( HTMLDivElement );
 			expect( actionButtonRef.current ).toBeInstanceOf(
 				HTMLButtonElement

package/src/notice/title.tsx

@@ -1,20 +1,21 @@
 import { forwardRef } from '@wordpress/element';
-import { useRender, mergeProps } from '@base-ui/react';
+import clsx from 'clsx';
 import type { TitleProps } from './types';
+import { Text } from '../text';
 import styles from './style.module.css';
 
 /**
  * A short heading that communicates the main message of the notice.
  */
 export const Title = forwardRef< HTMLSpanElement, TitleProps >(
-	function NoticeTitle( { render, ...props }, ref ) {
-		const element = useRender( {
-			defaultTagName: 'span',
-			render,
-			ref,
-			props: mergeProps< 'span' >( { className: styles.title }, props ),
-		} );
-
-		return element;
+	function NoticeTitle( { className, ...props }, ref ) {
+		return (
+			<Text
+				ref={ ref }
+				variant="heading-md"
+				className={ clsx( styles.title, className ) }
+				{ ...props }
+			/>
+		);
 	}
 );

package/src/notice/types.ts

@@ -3,6 +3,7 @@ import type { ComponentProps } from '../utils/types';
 import type { IconProps } from '../icon/types';
 import type { ButtonProps } from '../button/types';
 import type { IconButtonProps } from '../icon-button/types';
+import type { LinkProps } from '../link/types';
 
 export type NoticeIntent = 'warning' | 'success' | 'error' | 'info' | 'neutral';
 
@@ -47,7 +48,7 @@ export interface TitleProps extends ComponentProps< 'span' > {
 	children?: ReactNode;
 }
 
-export interface DescriptionProps extends ComponentProps< 'div' > {
+export interface DescriptionProps extends ComponentProps< 'span' > {
 	/**
 	 * The description text of the notice.
 	 */
@@ -92,7 +93,7 @@ export interface ActionButtonProps
 	children?: ReactNode;
 }
 
-export interface ActionLinkProps extends ComponentProps< 'a' > {
+export interface ActionLinkProps extends Omit< LinkProps, 'variant' | 'tone' > {
 	/**
 	 * The content to be rendered inside the component.
 	 */

package/src/tabs/style.module.css

@@ -119,7 +119,7 @@
 		align-items: center;
 
 		/* Appearance */
-		cursor: pointer;
+		cursor: var(--wpds-cursor-control);
 
 		/* Typography */
 		font-family: var(--wpds-font-family-body);

package/src/text/index.ts

@@ -0,0 +1 @@
+export { Text } from './text';

package/src/text/stories/index.story.tsx

@@ -0,0 +1,68 @@
+/* eslint-disable jsx-a11y/heading-has-content */
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Text } from '../index';
+import { Stack } from '../../stack';
+
+const meta: Meta< typeof Text > = {
+	title: 'Design System/Components/Text',
+	component: Text,
+};
+export default meta;
+
+type Story = StoryObj< typeof Text >;
+
+export const Default: Story = {
+	args: {
+		variant: 'body-md',
+		children: 'The quick brown fox jumps over the lazy dog.',
+	},
+};
+
+export const AllVariants: Story = {
+	render: () => (
+		<Stack
+			direction="column"
+			gap="lg"
+			style={ { color: 'var(--wpds-color-fg-content-neutral)' } }
+		>
+			{ (
+				[
+					'heading-2xl',
+					'heading-xl',
+					'heading-lg',
+					'heading-md',
+					'heading-sm',
+					'body-xl',
+					'body-lg',
+					'body-md',
+					'body-sm',
+				] as const
+			 ).map( ( variant ) => (
+				<Stack key={ variant } direction="column" gap="xs">
+					<Text variant="heading-sm">{ variant }</Text>
+					<Text variant={ variant }>
+						The quick brown fox jumps over the lazy dog.
+					</Text>
+				</Stack>
+			) ) }
+		</Stack>
+	),
+};
+
+export const WithRenderProp: Story = {
+	render: () => (
+		<Stack direction="column" gap="md">
+			<Text variant="heading-2xl" render={ <h1 /> }>
+				Page Title
+			</Text>
+			<Text variant="heading-xl" render={ <h2 /> }>
+				Section Heading
+			</Text>
+			<Text variant="body-md" render={ <p /> }>
+				A paragraph of body text rendered as a semantic paragraph
+				element.
+			</Text>
+		</Stack>
+	),
+};
+/* eslint-enable jsx-a11y/heading-has-content */

package/src/text/style.module.css

@@ -0,0 +1,67 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.heading-2xl {
+		font-family: var(--wpds-font-family-heading);
+		font-size: var(--wpds-font-size-2xl);
+		line-height: var(--wpds-font-line-height-2xl);
+		font-weight: var(--wpds-font-weight-medium);
+	}
+
+	.heading-xl {
+		font-family: var(--wpds-font-family-heading);
+		font-size: var(--wpds-font-size-xl);
+		line-height: var(--wpds-font-line-height-md);
+		font-weight: var(--wpds-font-weight-medium);
+	}
+
+	.heading-lg {
+		font-family: var(--wpds-font-family-heading);
+		font-size: var(--wpds-font-size-lg);
+		line-height: var(--wpds-font-line-height-sm);
+		font-weight: var(--wpds-font-weight-medium);
+	}
+
+	.heading-md {
+		font-family: var(--wpds-font-family-heading);
+		font-size: var(--wpds-font-size-md);
+		line-height: var(--wpds-font-line-height-sm);
+		font-weight: var(--wpds-font-weight-medium);
+	}
+
+	.heading-sm {
+		font-family: var(--wpds-font-family-heading);
+		font-size: var(--wpds-font-size-xs);
+		line-height: var(--wpds-font-line-height-xs);
+		font-weight: var(--wpds-font-weight-medium);
+		text-transform: uppercase;
+	}
+
+	.body-xl {
+		font-family: var(--wpds-font-family-body);
+		font-size: var(--wpds-font-size-xl);
+		line-height: var(--wpds-font-line-height-xl);
+		font-weight: var(--wpds-font-weight-regular);
+	}
+
+	.body-lg {
+		font-family: var(--wpds-font-family-body);
+		font-size: var(--wpds-font-size-lg);
+		line-height: var(--wpds-font-line-height-md);
+		font-weight: var(--wpds-font-weight-regular);
+	}
+
+	.body-md {
+		font-family: var(--wpds-font-family-body);
+		font-size: var(--wpds-font-size-md);
+		line-height: var(--wpds-font-line-height-sm);
+		font-weight: var(--wpds-font-weight-regular);
+	}
+
+	.body-sm {
+		font-family: var(--wpds-font-family-body);
+		font-size: var(--wpds-font-size-sm);
+		line-height: var(--wpds-font-line-height-xs);
+		font-weight: var(--wpds-font-weight-regular);
+	}
+}

package/src/text/test/index.test.tsx

@@ -0,0 +1,46 @@
+import { render, screen } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import { Text } from '../index';
+
+describe( 'Text', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLSpanElement >();
+
+		render( <Text ref={ ref }>Content</Text> );
+
+		expect( ref.current ).toBeInstanceOf( HTMLSpanElement );
+	} );
+
+	it( 'renders children', () => {
+		render( <Text>Hello world</Text> );
+
+		expect( screen.getByText( 'Hello world' ) ).toBeVisible();
+	} );
+
+	it( 'forwards props to the rendered element', () => {
+		render( <Text data-testid="text">Content</Text> );
+
+		expect( screen.getByTestId( 'text' ) ).toBeInTheDocument();
+	} );
+
+	it( 'forwards the className to the rendered element', () => {
+		render(
+			<Text data-testid="text" className="custom-class">
+				Content
+			</Text>
+		);
+
+		expect( screen.getByTestId( 'text' ) ).toHaveClass( 'custom-class' );
+	} );
+
+	it( 'supports the render prop', () => {
+		render(
+			// eslint-disable-next-line jsx-a11y/heading-has-content
+			<Text render={ <h2 /> }>Section title</Text>
+		);
+
+		expect(
+			screen.getByRole( 'heading', { level: 2, name: 'Section title' } )
+		).toBeVisible();
+	} );
+} );

package/src/text/text.tsx

@@ -0,0 +1,25 @@
+import { useRender, mergeProps } from '@base-ui/react';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { type TextProps } from './types';
+import styles from './style.module.css';
+
+/**
+ * A text component for rendering content with predefined typographic variants.
+ * Built on design tokens for consistent typography across the UI.
+ */
+export const Text = forwardRef< HTMLSpanElement, TextProps >( function Text(
+	{ variant = 'body-md', render, className, ...props },
+	ref
+) {
+	const element = useRender( {
+		render,
+		defaultTagName: 'span',
+		ref,
+		props: mergeProps< 'span' >( props, {
+			className: clsx( styles[ variant ], className ),
+		} ),
+	} );
+
+	return element;
+} );

package/src/text/types.ts

@@ -0,0 +1,25 @@
+import { type ComponentProps } from '../utils/types';
+
+export interface TextProps extends ComponentProps< 'span' > {
+	/**
+	 * The typographic variant to apply, controlling font family, size,
+	 * line height, and weight.
+	 *
+	 * @default "body-md"
+	 */
+	variant?:
+		| 'heading-2xl'
+		| 'heading-xl'
+		| 'heading-lg'
+		| 'heading-md'
+		| 'heading-sm'
+		| 'body-xl'
+		| 'body-lg'
+		| 'body-md'
+		| 'body-sm';
+
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: React.ReactNode;
+}

package/src/tooltip/popup.tsx

@@ -16,7 +16,7 @@ const ThemeProvider: typeof ThemeProviderType =
 const Popup = forwardRef< HTMLDivElement, PopupProps >( function TooltipPopup(
 	{
 		align = 'center',
-		side = 'bottom',
+		side = 'top',
 		sideOffset = 4,
 		children,
 		className,