@wordpress/ui 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/ui",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "Themeable React UI components for the WordPress Design System.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -44,24 +44,24 @@
 	"sideEffects": false,
 	"dependencies": {
 		"@base-ui/react": "^1.2.0",
-		"@wordpress/a11y": "^4.41.0",
-		"@wordpress/compose": "^7.41.0",
-		"@wordpress/element": "^6.41.0",
-		"@wordpress/i18n": "^6.14.0",
-		"@wordpress/icons": "^11.8.0",
-		"@wordpress/keycodes": "^4.41.0",
-		"@wordpress/primitives": "^4.41.0",
-		"@wordpress/private-apis": "^1.41.0",
-		"@wordpress/theme": "^0.8.0",
+		"@wordpress/a11y": "^4.42.0",
+		"@wordpress/compose": "^7.42.0",
+		"@wordpress/element": "^6.42.0",
+		"@wordpress/i18n": "^6.15.0",
+		"@wordpress/icons": "^12.0.0",
+		"@wordpress/keycodes": "^4.42.0",
+		"@wordpress/primitives": "^4.42.0",
+		"@wordpress/private-apis": "^1.42.0",
+		"@wordpress/theme": "^0.9.0",
 		"clsx": "^2.1.1"
 	},
 	"devDependencies": {
-		"@storybook/addon-docs": "^10.1.11",
-		"@storybook/react-vite": "^10.1.11",
+		"@storybook/addon-docs": "^10.2.8",
+		"@storybook/react-vite": "^10.2.8",
 		"@testing-library/jest-dom": "^6.9.1",
 		"@types/jest": "^29.5.14",
 		"@types/node": "^20.17.10",
-		"storybook": "^10.1.11"
+		"storybook": "^10.2.8"
 	},
 	"peerDependencies": {
 		"react": "^18.0.0",
@@ -70,5 +70,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "8bfc179b9aed74c0a6dd6e8edf7a49e40e4f87cc"
+	"gitHead": "c20787b1778ae64c2db65643b1c236309d68e6ba"
 }

package/src/badge/style.module.css

@@ -42,7 +42,10 @@
 	}
 
 	.is-none-intent {
-		background-color: var(--wpds-color-bg-surface-neutral);
-		color: var(--wpds-color-fg-content-neutral-weak);
+		background-color: var(--wpds-color-bg-surface-neutral-strong);
+		color: var(--wpds-color-fg-content-neutral);
+		border: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral);
+		padding-block: calc(var(--wpds-dimension-padding-xs) - var(--wpds-border-width-xs));
+		padding-inline: calc(var(--wpds-dimension-padding-sm) - var(--wpds-border-width-xs));
 	}
 }

package/src/button/style.module.css

@@ -50,6 +50,7 @@
 		line-height: var(--wpds-font-line-height-sm);
 		text-decoration: none;
 		color: var(--wp-ui-button-foreground-color);
+		cursor: var(--wpds-cursor-control);
 
 		@media not ( prefers-reduced-motion ) {
 			transition: color 0.1s ease-out;
@@ -61,6 +62,7 @@
 
 		/* Use pointer cursor for buttons that are links */
 		&[href] {
+			/* stylelint-disable-next-line declaration-property-value-disallowed-list -- Links should always use pointer. */
 			cursor: pointer;
 		}
 

package/src/card/content.tsx

@@ -0,0 +1,20 @@
+import { mergeProps, useRender } from '@base-ui/react';
+import { forwardRef } from '@wordpress/element';
+import styles from './style.module.css';
+import type { ContentProps } from './types';
+
+/**
+ * The main content area of the card.
+ */
+export const Content = forwardRef< HTMLDivElement, ContentProps >(
+	function CardContent( { render, ...props }, ref ) {
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >( { className: styles.content }, props ),
+		} );
+
+		return element;
+	}
+);

package/src/card/full-bleed.tsx

@@ -0,0 +1,26 @@
+import { mergeProps, useRender } from '@base-ui/react';
+import { forwardRef } from '@wordpress/element';
+import styles from './style.module.css';
+import type { FullBleedProps } from './types';
+
+/**
+ * A container that breaks out of the card's padding to span edge-to-edge.
+ * Useful for full-width images, dividers, or embedded content.
+ *
+ * Must be used as a direct child of `Card.Content` or `Card.Header`.
+ */
+export const FullBleed = forwardRef< HTMLDivElement, FullBleedProps >(
+	function CardFullBleed( { render, ...props }, ref ) {
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >(
+				{ className: styles.fullbleed },
+				props
+			),
+		} );
+
+		return element;
+	}
+);

package/src/card/header.tsx

@@ -0,0 +1,21 @@
+import { mergeProps, useRender } from '@base-ui/react';
+import { forwardRef } from '@wordpress/element';
+import styles from './style.module.css';
+import type { HeaderProps } from './types';
+
+/**
+ * A structural container for the card's heading area, typically containing
+ * `Card.Title`.
+ */
+export const Header = forwardRef< HTMLDivElement, HeaderProps >(
+	function CardHeader( { render, ...props }, ref ) {
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >( { className: styles.header }, props ),
+		} );
+
+		return element;
+	}
+);

package/src/card/index.ts

@@ -0,0 +1,7 @@
+import { Root } from './root';
+import { Header } from './header';
+import { Content } from './content';
+import { FullBleed } from './full-bleed';
+import { Title } from './title';
+
+export { Root, Header, Content, FullBleed, Title };

package/src/card/root.tsx

@@ -0,0 +1,42 @@
+import { mergeProps, useRender } from '@base-ui/react';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import resetStyles from '../utils/css/resets.module.css';
+import styles from './style.module.css';
+import type { RootProps } from './types';
+
+/**
+ * A visually contained surface that groups related content and actions.
+ *
+ * ```jsx
+ * import { Card } from '@wordpress/ui';
+ *
+ * function MyComponent() {
+ * 	return (
+ * 		<Card.Root>
+ * 			<Card.Header>
+ * 				<Card.Title>Heading</Card.Title>
+ * 			</Card.Header>
+ * 			<Card.Content>
+ * 				<p>Main content here.</p>
+ * 			</Card.Content>
+ * 		</Card.Root>
+ * 	);
+ * }
+ * ```
+ */
+export const Root = forwardRef< HTMLDivElement, RootProps >( function Card(
+	{ render, ...restProps },
+	ref
+) {
+	const mergedClassName = clsx( styles.root, resetStyles[ 'box-sizing' ] );
+
+	const element = useRender( {
+		defaultTagName: 'div',
+		render,
+		ref,
+		props: mergeProps< 'div' >( { className: mergedClassName }, restProps ),
+	} );
+
+	return element;
+} );

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

@@ -0,0 +1,128 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import * as Card from '../index';
+
+/**
+ * Temporary text component for story examples. This will be replaced by an
+ * official DS `<Text />` component once it's available.
+ */
+function Text( { children }: { children: React.ReactNode } ) {
+	return (
+		<p
+			style={ {
+				margin: 0,
+				fontFamily: 'var(--wpds-font-family-body)',
+				fontSize: 'var(--wpds-font-size-md)',
+				fontWeight: 'var(--wpds-font-weight-regular)',
+				lineHeight: 'var(--wpds-font-line-height-sm)',
+				textWrap: 'pretty',
+				color: 'var(--wpds-color-fg-content-neutral-weak)',
+			} }
+		>
+			{ children }
+		</p>
+	);
+}
+
+const meta: Meta< typeof Card.Root > = {
+	title: 'Design System/Components/Card',
+	component: Card.Root,
+	subcomponents: {
+		'Card.Header': Card.Header,
+		'Card.Content': Card.Content,
+		'Card.FullBleed': Card.FullBleed,
+		'Card.Title': Card.Title,
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof Card.Root >;
+
+export const Default: Story = {
+	args: {
+		children: (
+			<>
+				<Card.Header>
+					<Card.Title>Card title</Card.Title>
+				</Card.Header>
+				<Card.Content>
+					<Text>
+						This is the main content area. It can contain any
+						elements. This is the main content area. It can contain
+						any elements. This is the main content area. It can
+						contain any elements. This is the main content area. It
+						can contain any elements. This is the main content area.
+						It can contain any elements. This is the main content
+						area. It can contain any elements.
+					</Text>
+					<Text>
+						This is the main content area. It can contain any
+						elements.
+					</Text>
+				</Card.Content>
+			</>
+		),
+	},
+};
+
+/**
+ * `Card.FullBleed` breaks out of the card's padding to span
+ * edge-to-edge. Useful for images, dividers, or embedded content.
+ */
+export const WithFullBleed: Story = {
+	args: {
+		children: (
+			<>
+				<Card.Header>
+					<Card.Title>Featured image</Card.Title>
+				</Card.Header>
+				<Card.Content>
+					<Card.FullBleed>
+						<div
+							style={ {
+								height: 160,
+								background:
+									'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+							} }
+						/>
+					</Card.FullBleed>
+					<Text>Content below the full-bleed area.</Text>
+				</Card.Content>
+			</>
+		),
+	},
+};
+
+/**
+ * A minimal card with only a header.
+ */
+export const HeaderOnly: Story = {
+	args: {
+		children: (
+			<Card.Header>
+				<Card.Title>Simple card</Card.Title>
+			</Card.Header>
+		),
+	},
+};
+
+/**
+ * Use the `render` prop to change the underlying HTML elements for
+ * better semantics. Here, `Card.Root` renders as a `<section>` and
+ * `Card.Title` renders as an `<h2>`.
+ */
+export const CustomSemantics: Story = {
+	args: {
+		render: <section />,
+		children: (
+			<>
+				<Card.Header>
+					{ /* eslint-disable-next-line jsx-a11y/heading-has-content -- content provided via render prop */ }
+					<Card.Title render={ <h2 /> }>Section heading</Card.Title>
+				</Card.Header>
+				<Card.Content>
+					<Text>Semantically meaningful card content.</Text>
+				</Card.Content>
+			</>
+		),
+	},
+};

package/src/card/style.module.css

@@ -0,0 +1,48 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.root {
+		--wp-ui-card-padding: var(--wpds-dimension-padding-2xl);
+		--wp-ui-card-header-content-gap: var(--wpds-dimension-gap-xl);
+		--wp-ui-card-header-content-margin: calc(var(--wp-ui-card-header-content-gap) - var(--wp-ui-card-padding));
+
+		display: flex;
+		flex-direction: column;
+		border: 1px solid var(--wpds-color-stroke-surface-neutral-weak);
+		border-radius: var(--wpds-border-radius-lg);
+		background-color: var(--wpds-color-bg-surface-neutral-strong);
+	}
+
+	/* Padding is applied to the individual header/content elements to enable
+	 * the higher-level `CollapsibleCard` component to be fully clickable
+	 * to expand/collapse the card.
+	*/
+	.header,
+	.content {
+		padding: var(--wp-ui-card-padding);
+
+		&:not(:first-child):not(:last-child) {
+			padding-block-end: 0;
+		}
+	}
+
+	/* Custom vertical gap between header and content */
+	.header + .content {
+		padding-block-start: 0;
+		margin-block-start: var(--wp-ui-card-header-content-margin);
+	}
+
+	.fullbleed {
+		margin-inline: calc(-1 * var(--wp-ui-card-padding));
+		width: calc(100% + 2 * var(--wp-ui-card-padding));
+	}
+
+	.title {
+		margin: 0;
+		font-family: var(--wpds-font-family-heading);
+		font-size: var(--wpds-font-size-lg);
+		font-weight: var(--wpds-font-weight-medium);
+		line-height: var(--wpds-font-line-height-sm);
+		color: var(--wpds-color-fg-content-neutral);
+	}
+}

package/src/card/test/index.test.tsx

@@ -0,0 +1,96 @@
+import { render, screen } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import * as Card from '../index';
+
+describe( 'Card', () => {
+	describe( 'basic behaviour', () => {
+		it( 'forwards ref', () => {
+			const rootRef = createRef< HTMLDivElement >();
+			const headerRef = createRef< HTMLDivElement >();
+			const contentRef = createRef< HTMLDivElement >();
+			const fullBleedRef = createRef< HTMLDivElement >();
+			const titleRef = createRef< HTMLDivElement >();
+
+			render(
+				<Card.Root ref={ rootRef }>
+					<Card.Header ref={ headerRef }>
+						<Card.Title ref={ titleRef }>Title</Card.Title>
+					</Card.Header>
+					<Card.Content ref={ contentRef }>
+						<Card.FullBleed ref={ fullBleedRef }>
+							Full width
+						</Card.FullBleed>
+					</Card.Content>
+				</Card.Root>
+			);
+
+			expect( rootRef.current ).toBeInstanceOf( HTMLDivElement );
+			expect( headerRef.current ).toBeInstanceOf( HTMLDivElement );
+			expect( contentRef.current ).toBeInstanceOf( HTMLDivElement );
+			expect( fullBleedRef.current ).toBeInstanceOf( HTMLDivElement );
+			expect( titleRef.current ).toBeInstanceOf( HTMLDivElement );
+		} );
+
+		it( 'renders content', () => {
+			render(
+				<Card.Root>
+					<Card.Header>
+						<Card.Title>Card heading</Card.Title>
+					</Card.Header>
+					<Card.Content>
+						<p>Main content</p>
+					</Card.Content>
+				</Card.Root>
+			);
+
+			expect( screen.getByText( 'Card heading' ) ).toBeVisible();
+			expect( screen.getByText( 'Main content' ) ).toBeVisible();
+		} );
+	} );
+
+	describe( 'fullbleed', () => {
+		it( 'renders children', () => {
+			render(
+				<Card.Root>
+					<Card.Content>
+						<Card.FullBleed>
+							<img
+								src="https://example.com/image.jpg"
+								alt="test"
+							/>
+						</Card.FullBleed>
+					</Card.Content>
+				</Card.Root>
+			);
+
+			expect( screen.getByRole( 'img', { name: 'test' } ) ).toBeVisible();
+		} );
+	} );
+
+	describe( 'render prop', () => {
+		it( 'allows Root to render as a different element', () => {
+			render(
+				<Card.Root render={ <section /> } data-testid="card">
+					<Card.Content>Content</Card.Content>
+				</Card.Root>
+			);
+
+			expect( screen.getByTestId( 'card' ).tagName ).toBe( 'SECTION' );
+		} );
+
+		it( 'allows Title to render as a heading element', () => {
+			render(
+				<Card.Root>
+					<Card.Header>
+						{ /* eslint-disable-next-line jsx-a11y/heading-has-content -- content provided via render prop */ }
+						<Card.Title render={ <h2 /> }>Heading</Card.Title>
+					</Card.Header>
+				</Card.Root>
+			);
+
+			expect(
+				screen.getByRole( 'heading', { level: 2, name: 'Heading' } )
+			).toBeVisible();
+		} );
+	} );
+} );

package/src/card/title.tsx

@@ -0,0 +1,22 @@
+import { mergeProps, useRender } from '@base-ui/react';
+import { forwardRef } from '@wordpress/element';
+import styles from './style.module.css';
+import type { TitleProps } from './types';
+
+/**
+ * The title for a card. Renders as a `<div>` by default — use the `render`
+ * prop to swap in a semantic heading element when appropriate.
+ */
+export const Title = forwardRef< HTMLDivElement, TitleProps >(
+	function CardTitle( { render, ...props }, ref ) {
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			// TODO: use `Text` component instead, when ready
+			props: mergeProps< 'div' >( { className: styles.title }, props ),
+		} );
+
+		return element;
+	}
+);

package/src/card/types.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+import type { ComponentProps } from '../utils/types';
+
+export interface RootProps extends ComponentProps< 'div' > {
+	/**
+	 * The content to be rendered inside the card.
+	 */
+	children?: ReactNode;
+}
+
+export interface HeaderProps extends ComponentProps< 'div' > {
+	/**
+	 * The content to be rendered inside the header.
+	 */
+	children?: ReactNode;
+}
+
+export interface ContentProps extends ComponentProps< 'div' > {
+	/**
+	 * The content to be rendered inside the content area.
+	 */
+	children?: ReactNode;
+}
+
+export interface FullBleedProps extends ComponentProps< 'div' > {
+	/**
+	 * The content to be rendered edge-to-edge, breaking out of the
+	 * card's padding.
+	 */
+	children?: ReactNode;
+}
+
+export interface TitleProps extends ComponentProps< 'div' > {
+	/**
+	 * The title text for the card.
+	 */
+	children?: ReactNode;
+}

package/src/collapsible/index.ts

@@ -0,0 +1,5 @@
+import { Panel } from './panel';
+import { Root } from './root';
+import { Trigger } from './trigger';
+
+export { Root, Trigger, Panel };

package/src/collapsible/panel.tsx

@@ -0,0 +1,16 @@
+import { Collapsible as _Collapsible } from '@base-ui/react/collapsible';
+import { forwardRef } from '@wordpress/element';
+import type { PanelProps } from './types';
+
+/**
+ * A panel with the collapsible contents. Hidden when collapsed, visible
+ * when expanded.
+ *
+ * `Collapsible` is a collection of React components that combine to render
+ * a collapsible panel controlled by a button.
+ */
+export const Panel = forwardRef< HTMLDivElement, PanelProps >(
+	function CollapsiblePanel( props, forwardedRef ) {
+		return <_Collapsible.Panel ref={ forwardedRef } { ...props } />;
+	}
+);

package/src/collapsible/root.tsx

@@ -0,0 +1,15 @@
+import { Collapsible as _Collapsible } from '@base-ui/react/collapsible';
+import { forwardRef } from '@wordpress/element';
+import type { RootProps } from './types';
+
+/**
+ * Groups all parts of the collapsible.
+ *
+ * `Collapsible` is a collection of React components that combine to render
+ * a collapsible panel controlled by a button.
+ */
+export const Root = forwardRef< HTMLDivElement, RootProps >(
+	function CollapsibleRoot( props, forwardedRef ) {
+		return <_Collapsible.Root ref={ forwardedRef } { ...props } />;
+	}
+);

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

@@ -0,0 +1,108 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from '@wordpress/element';
+import * as Collapsible from '../index';
+
+const meta: Meta< typeof Collapsible.Root > = {
+	title: 'Design System/Components/Collapsible',
+	component: Collapsible.Root,
+	subcomponents: {
+		'Collapsible.Trigger': Collapsible.Trigger,
+		'Collapsible.Panel': Collapsible.Panel,
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof Collapsible.Root >;
+
+export const Default: Story = {
+	args: {
+		children: (
+			<>
+				<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+				<Collapsible.Panel>
+					<p>Collapsible content here.</p>
+				</Collapsible.Panel>
+			</>
+		),
+	},
+};
+
+export const DefaultOpen: Story = {
+	argTypes: { open: { control: false } },
+	args: {
+		defaultOpen: true,
+		children: (
+			<>
+				<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+				<Collapsible.Panel>
+					<p>This panel is open by default.</p>
+				</Collapsible.Panel>
+			</>
+		),
+	},
+};
+
+export const Disabled: Story = {
+	args: {
+		disabled: true,
+		children: (
+			<>
+				<Collapsible.Trigger>Toggle (disabled)</Collapsible.Trigger>
+				<Collapsible.Panel>
+					<p>This content cannot be toggled.</p>
+				</Collapsible.Panel>
+			</>
+		),
+	},
+};
+
+/**
+ * When `hiddenUntilFound` is set on `Collapsible.Panel`, the collapsed content
+ * remains in the DOM using the `hidden="until-found"` HTML attribute instead of
+ * being removed entirely. This lets the browser's native page search (Ctrl/Cmd+F)
+ * find text inside collapsed panels and automatically expand them to reveal the
+ * match — improving discoverability without sacrificing the collapsed layout.
+ */
+export const HiddenUntilFound: Story = {
+	render: function HiddenUntilFound() {
+		return (
+			<div>
+				<p>
+					Use the browser&apos;s find-in-page (Ctrl/Cmd+F) to search
+					for &quot;hidden treasure&quot;. The collapsed panel will
+					automatically expand to reveal the match.
+				</p>
+				<Collapsible.Root>
+					<Collapsible.Trigger>Expand to reveal</Collapsible.Trigger>
+					<Collapsible.Panel hiddenUntilFound>
+						<p>
+							This is the hidden treasure that can be found via
+							the browser&apos;s built-in page search even while
+							the panel is collapsed.
+						</p>
+					</Collapsible.Panel>
+				</Collapsible.Root>
+			</div>
+		);
+	},
+};
+
+export const Controlled: Story = {
+	argTypes: {
+		open: { control: false },
+		defaultOpen: { control: false },
+	},
+	render: function Controlled() {
+		const [ open, setOpen ] = useState( false );
+		return (
+			<Collapsible.Root open={ open } onOpenChange={ setOpen }>
+				<Collapsible.Trigger>
+					{ open ? 'Close' : 'Open' }
+				</Collapsible.Trigger>
+				<Collapsible.Panel>
+					<p>Controlled collapsible panel.</p>
+				</Collapsible.Panel>
+			</Collapsible.Root>
+		);
+	},
+};