@wordpress/ui 0.4.0 → 0.5.0

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

@@ -0,0 +1,192 @@
+import { Fragment, useState } from '@wordpress/element';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { cog } from '@wordpress/icons';
+import { Button } from '../index';
+
+const meta: Meta< typeof Button > = {
+	title: 'Design System/Components/Button',
+	component: Button,
+	argTypes: {
+		'aria-pressed': {
+			control: { type: 'boolean' },
+		},
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof Button >;
+
+export const Default: Story = {
+	args: {
+		children: 'Button',
+	},
+};
+
+export const Outline: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		variant: 'outline',
+	},
+};
+
+export const Minimal: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		variant: 'minimal',
+	},
+};
+
+export const Compact: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		size: 'compact',
+	},
+};
+
+export const Small: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		size: 'small',
+	},
+};
+
+export const Neutral: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		tone: 'neutral',
+	},
+};
+
+export const NeutralOutline: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		tone: 'neutral',
+		variant: 'outline',
+	},
+};
+
+export const Unstyled: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		variant: 'unstyled',
+	},
+};
+
+export const AllTonesAndVariants: Story = {
+	...Default,
+	render: ( args ) => (
+		<div
+			style={ {
+				display: 'grid',
+				gridTemplateColumns: 'max-content repeat(2, min-content)',
+				color: 'var(--wpds-color-fg-content-neutral)',
+			} }
+		>
+			<div></div>
+			<div style={ { textAlign: 'center' } }>Resting</div>
+			<div style={ { textAlign: 'center' } }>Disabled</div>
+			{ ( [ 'brand', 'neutral' ] as const ).map( ( tone ) => (
+				<Fragment key={ tone }>
+					{ (
+						[ 'solid', 'outline', 'minimal', 'unstyled' ] as const
+					 ).map( ( variant ) => (
+						<Fragment key={ variant }>
+							<div
+								style={ {
+									paddingInlineEnd: '1rem',
+									display: 'flex',
+									alignItems: 'center',
+								} }
+							>
+								{ variant }, { tone }
+							</div>
+							<div
+								style={ {
+									padding: '0.5rem 1rem',
+									display: 'flex',
+									alignItems: 'center',
+								} }
+							>
+								<Button
+									{ ...args }
+									tone={ tone }
+									variant={ variant }
+								/>
+							</div>
+							<div
+								style={ {
+									padding: '0.5rem 1rem',
+									display: 'flex',
+									alignItems: 'center',
+								} }
+							>
+								<Button
+									{ ...args }
+									tone={ tone }
+									variant={ variant }
+									disabled
+								/>
+							</div>
+						</Fragment>
+					) ) }
+				</Fragment>
+			) ) }
+		</div>
+	),
+};
+
+export const WithIcon: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		children: (
+			<>
+				<Button.Icon icon={ cog } />
+				Button
+			</>
+		),
+	},
+};
+
+export const Loading: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		loading: true,
+		loadingAnnouncement: 'Saving data',
+	},
+};
+
+/**
+ * The pressed state is only available for buttons with `tone="neutral"` and
+ * `variant="minimal"`. This represents a toggle button that is currently in an
+ * active/pressed state.
+ */
+export const Pressed: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		tone: 'neutral',
+		variant: 'minimal',
+	},
+	render: ( args ) => {
+		const [ isPressed, setIsPressed ] = useState( true );
+
+		return (
+			<Button
+				{ ...args }
+				aria-pressed={ isPressed }
+				onClick={ () => setIsPressed( ! isPressed ) }
+			>
+				Button
+			</Button>
+		);
+	},
+};

package/src/button/style.module.css

@@ -0,0 +1,232 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.button,
+	.is-unstyled {
+		appearance: none;
+		padding: 0;
+	}
+
+	.button {
+		/* Internal variables */
+		--wp-ui-button-font-weight: 499;
+
+		--wp-ui-button-background-color: var(--wpds-color-bg-interactive-brand-strong);
+		--wp-ui-button-background-color-active: var(--wpds-color-bg-interactive-brand-strong-active);
+		--wp-ui-button-background-color-disabled: var(--wpds-color-bg-interactive-neutral-strong-disabled);
+		--wp-ui-button-foreground-color: var(--wpds-color-fg-interactive-brand-strong);
+		--wp-ui-button-foreground-color-active: var(--wpds-color-fg-interactive-brand-strong-active);
+		--wp-ui-button-foreground-color-disabled: var(--wpds-color-fg-interactive-neutral-strong-disabled);
+		--wp-ui-button-padding-inline: calc(3 * var(--wpds-dimension-base)); /* TODO: Create new interactive padding tokens */
+		--wp-ui-button-height: 40px;
+		--wp-ui-button-aspect-ratio: auto; /* Useful for overrides such as icon buttons */
+		--wp-ui-button-font-size: var(--wpds-font-size-md);
+
+		/* by default, borders have the same color as the background */
+		--wp-ui-button-border-color: var(--wp-ui-button-background-color);
+		--wp-ui-button-border-color-active: var(--wp-ui-button-background-color-active);
+		--wp-ui-button-border-color-disabled: var(--wp-ui-button-background-color-disabled);
+
+		/* Styles */
+		position: relative;
+		display: inline-flex;
+		justify-content: center;
+		align-items: center;
+		gap: calc(2 * var(--wpds-dimension-base)); /* TODO: Consider new interactive/control gap tokens */
+		aspect-ratio: var(--wp-ui-button-aspect-ratio);
+		height: var(--wp-ui-button-height);
+		padding-inline: var(--wp-ui-button-padding-inline);
+		border-style: solid;
+		border-width: 1px;
+		border-color: var(--wp-ui-button-border-color);
+		border-radius: var(--wpds-border-radius-surface-sm);
+		background-color: var(--wp-ui-button-background-color);
+		background-clip: padding-box;
+		font-family: var(--wpds-font-family-body);
+		font-size: var(--wp-ui-button-font-size);
+		font-weight: var(--wp-ui-button-font-weight);
+		line-height: var(--wpds-font-line-height-sm);
+		text-decoration: none;
+		color: var(--wp-ui-button-foreground-color);
+
+		@media not ( prefers-reduced-motion ) {
+			transition: color 0.1s ease-out;
+
+			* {
+				transition: opacity 0.1s ease-out;
+			}
+		}
+
+		/* Use pointer cursor for buttons that are links */
+		&[href] {
+			cursor: pointer;
+		}
+
+		/* Make sure that links rendered as children of `Button` use button styles */
+		*[href] {
+			color: inherit;
+			text-decoration: inherit;
+		}
+
+		/* States */
+		&:not([aria-disabled="true"]):is(:hover, :active, :focus) {
+			/* hover/active/focus states apply when the button is not disabled. A non
+			disabled, loading button will have hover/active/focus styles */
+			--wp-ui-button-background-color: var(--wp-ui-button-background-color-active);
+			--wp-ui-button-foreground-color: var(--wp-ui-button-foreground-color-active);
+			--wp-ui-button-border-color: var(--wp-ui-button-border-color-active);
+		}
+
+		&[aria-disabled="true"]:not(.is-loading) {
+			/* A loading button, even when disabled, won't "look" disabled */
+			--wp-ui-button-background-color: var(--wp-ui-button-background-color-disabled);
+			--wp-ui-button-foreground-color: var(--wp-ui-button-foreground-color-disabled);
+			--wp-ui-button-border-color: var(--wp-ui-button-border-color-disabled);
+
+			@media ( forced-colors: active ) {
+				border-color: GrayText;
+				color: GrayText;
+			}
+		}
+
+		/* Loading spinner — not animated and hidden unless in loading state */
+		&::before {
+			content: "";
+			position: absolute;
+			top: 50%;
+			inset-inline-start: 50%;
+			transform: translate(-50%, -50%);
+
+			display: block;
+			box-sizing: border-box;
+			height: var(--wp-ui-button-font-size);
+			aspect-ratio: 1;
+
+			border: var(--wpds-border-width-interactive-focus) solid;
+			border-block-start-color: var(--wp-ui-button-foreground-color);
+			border-inline-end-color: var(--wp-ui-button-foreground-color);
+			border-block-end-color: transparent;
+			border-inline-start-color: transparent;
+			border-radius: 50%;
+
+			pointer-events: none;
+			opacity: 0;
+
+			@media not ( prefers-reduced-motion ) {
+				transition: opacity 0.1s ease-out;
+			}
+		}
+	}
+
+	.is-small {
+		--wp-ui-button-padding-inline: calc(2 * var(--wpds-dimension-base)); /* TODO: Create new interactive padding tokens */
+		--wp-ui-button-height: 24px;
+	}
+
+	/* Variants (`tone` + `variant`) overrides compared to default styles */
+
+	/* All outline buttons have a border */
+	.is-brand {
+		/* no need to redefine variables for .is-brand.is-solid as it's the default variant */
+
+		/* Outline and minimal buttons use the same foreground color */
+		&.is-outline,
+		&.is-minimal {
+			--wp-ui-button-foreground-color: var(--wpds-color-fg-interactive-brand);
+			--wp-ui-button-foreground-color-active: var(--wpds-color-fg-interactive-brand-active);
+			--wp-ui-button-foreground-color-disabled: var(--wpds-color-fg-interactive-neutral-disabled);
+		}
+
+		&.is-outline {
+			--wp-ui-button-background-color: var(--wpds-color-bg-interactive-brand-weak);
+			--wp-ui-button-background-color-active: var(--wpds-color-bg-interactive-brand-weak-active);
+			--wp-ui-button-background-color-disabled: var(--wpds-color-bg-interactive-neutral-weak-disabled);
+			--wp-ui-button-border-color: var(--wpds-color-stroke-interactive-brand);
+			--wp-ui-button-border-color-active: var(--wpds-color-stroke-interactive-brand-active);
+			--wp-ui-button-border-color-disabled: var(--wpds-color-stroke-interactive-neutral-disabled);
+		}
+
+		&.is-minimal {
+			--wp-ui-button-background-color: var(--wpds-color-bg-interactive-brand-weak);
+			--wp-ui-button-background-color-active: var(--wpds-color-bg-interactive-brand-weak-active);
+			--wp-ui-button-background-color-disabled: var(--wpds-color-bg-interactive-neutral-weak-disabled);
+		}
+	}
+
+	.is-neutral {
+		&.is-solid {
+			--wp-ui-button-background-color: var(--wpds-color-bg-interactive-neutral-strong);
+			--wp-ui-button-background-color-active: var(--wpds-color-bg-interactive-neutral-strong-active);
+			--wp-ui-button-background-color-disabled: var(--wpds-color-bg-interactive-neutral-strong-disabled);
+			--wp-ui-button-foreground-color: var(--wpds-color-fg-interactive-neutral-strong);
+			--wp-ui-button-foreground-color-active: var(--wpds-color-fg-interactive-neutral-strong-active);
+			--wp-ui-button-foreground-color-disabled: var(--wpds-color-fg-interactive-neutral-strong-disabled);
+		}
+
+		/* Outline and minimal buttons use the same foreground color */
+		&.is-outline,
+		&.is-minimal {
+			--wp-ui-button-foreground-color: var(--wpds-color-fg-interactive-neutral);
+			--wp-ui-button-foreground-color-active: var(--wpds-color-fg-interactive-neutral-active);
+			--wp-ui-button-foreground-color-disabled: var(--wpds-color-fg-interactive-neutral-disabled);
+		}
+
+		&.is-outline {
+			--wp-ui-button-background-color: var(--wpds-color-bg-interactive-neutral-weak);
+			--wp-ui-button-background-color-active: var(--wpds-color-bg-interactive-neutral-weak-active);
+			--wp-ui-button-background-color-disabled: var(--wpds-color-bg-interactive-neutral-weak-disabled);
+			--wp-ui-button-border-color: var(--wpds-color-stroke-interactive-neutral);
+			--wp-ui-button-border-color-active: var(--wpds-color-stroke-interactive-neutral-active);
+			--wp-ui-button-border-color-disabled: var(--wpds-color-stroke-interactive-neutral-disabled);
+		}
+
+		&.is-minimal {
+			--wp-ui-button-background-color: var(--wpds-color-bg-interactive-neutral-weak);
+			--wp-ui-button-background-color-active: var(--wpds-color-bg-interactive-neutral-weak-active);
+			--wp-ui-button-background-color-disabled: var(--wpds-color-bg-interactive-neutral-weak-disabled);
+		}
+	}
+
+	.is-unstyled {
+		border: none;
+		background: none;
+	}
+
+	.is-compact {
+		--wp-ui-button-height: 32px;
+	}
+
+	.is-loading {
+		color: transparent;
+
+		* {
+			opacity: 0;
+		}
+
+		&::before {
+			transition-delay: 0.05s;
+			opacity: 1;
+
+			@media not ( prefers-reduced-motion ) {
+				animation: loading-animation 1s linear infinite;
+			}
+		}
+	}
+
+	[aria-pressed="true"].is-minimal.is-neutral {
+		--wp-ui-button-background-color: var(--wpds-color-bg-interactive-neutral-strong);
+		--wp-ui-button-background-color-active: var(--wpds-color-bg-interactive-neutral-strong);
+		--wp-ui-button-foreground-color: var(--wpds-color-fg-interactive-neutral-strong);
+		--wp-ui-button-foreground-color-active: var(--wpds-color-fg-interactive-neutral-strong);
+	}
+}
+
+@keyframes loading-animation {
+	0% {
+		transform: translate(-50%, -50%) rotate(0deg);
+	}
+
+	100% {
+		transform: translate(-50%, -50%) rotate(360deg);
+	}
+}

package/src/button/test/button.test.tsx

@@ -0,0 +1,89 @@
+import { createRef } from '@wordpress/element';
+import { screen, render } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Button } from '../index';
+
+describe( 'Button', () => {
+	it( 'renders a button element by default', () => {
+		render( <Button>Click me</Button> );
+
+		expect(
+			screen.getByRole( 'button', { name: 'Click me' } )
+		).toBeVisible();
+	} );
+
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLButtonElement >();
+
+		render( <Button ref={ ref }>Click me</Button> );
+
+		expect( ref.current ).toBeInstanceOf( HTMLButtonElement );
+	} );
+
+	it( 'is accessible when disabled by default', async () => {
+		const user = userEvent.setup();
+
+		const onClickMock = jest.fn();
+		render(
+			<Button disabled onClick={ onClickMock }>
+				Click me
+			</Button>
+		);
+		const button = screen.getByRole( 'button', { name: 'Click me' } );
+
+		expect( button ).toBeEnabled();
+		expect( button ).toHaveAttribute( 'aria-disabled', 'true' );
+
+		await user.keyboard( '{Tab}' );
+		expect( button ).toHaveFocus();
+
+		await user.keyboard( '{Enter}' );
+		expect( onClickMock ).not.toHaveBeenCalled();
+	} );
+
+	it( 'is disabled when loading', () => {
+		render( <Button loading>Click me</Button> );
+
+		const button = screen.getByRole( 'button', { name: 'Click me' } );
+
+		expect( button ).toBeEnabled();
+		expect( button ).toHaveAttribute( 'aria-disabled', 'true' );
+	} );
+
+	it( 'can be enabled explicitly when loading', () => {
+		render(
+			<Button loading disabled={ false }>
+				Click me
+			</Button>
+		);
+
+		const button = screen.getByRole( 'button', { name: 'Click me' } );
+
+		expect( button ).toBeEnabled();
+		expect( button ).not.toHaveAttribute( 'aria-disabled', 'true' );
+	} );
+
+	it( 'supports custom render prop while retaining the default focusable when disabled behavior', () => {
+		render(
+			// eslint-disable-next-line jsx-a11y/anchor-has-content
+			<Button render={ <a href="/" /> } nativeButton={ false } disabled>
+				Click me
+			</Button>
+		);
+		const button = screen.getByRole( 'button', { name: 'Click me' } );
+
+		expect( button ).toHaveAttribute( 'aria-disabled', 'true' );
+	} );
+
+	it( 'merges custom className with built-in classes', () => {
+		const customClass = 'my-button';
+		render(
+			<Button render={ <button /> } className={ customClass }>
+				Click me
+			</Button>
+		);
+		expect(
+			screen.getByRole( 'button', { name: 'Click me' } )
+		).toHaveClass( customClass );
+	} );
+} );

package/src/button/test/icon.test.tsx

@@ -0,0 +1,13 @@
+import { createRef } from '@wordpress/element';
+import { render } from '@testing-library/react';
+import { ButtonIcon } from '../icon';
+
+describe( 'Button.Icon', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< SVGSVGElement >();
+
+		render( <ButtonIcon ref={ ref } icon={ <svg /> } /> );
+
+		expect( ref.current ).toBeInstanceOf( SVGSVGElement );
+	} );
+} );

package/src/button/types.ts

@@ -0,0 +1,72 @@
+import { type ReactNode, type HTMLAttributes } from 'react';
+import type { Button as _Button } from '@base-ui/react/button';
+import type { ComponentProps } from '../utils/types';
+
+type _ButtonProps = ComponentProps< typeof _Button >;
+
+export interface ButtonProps
+	extends Omit< _ButtonProps, 'disabled' | 'aria-pressed' > {
+	/**
+	 * The variant of the button. Variants describe the visual style treatment
+	 * of the button.
+	 *
+	 * @default "solid"
+	 */
+	variant?: 'solid' | 'outline' | 'minimal' | 'unstyled';
+
+	/**
+	 * The tone of the button, describing a semantic color intent:
+	 *
+	 * - `'brand': for the most prominent actions, using the brand colors.
+	 * - `'neutral'` for less prominent actions.
+	 *
+	 * @default "brand"
+	 */
+	tone?: 'brand' | 'neutral';
+
+	/**
+	 * The size of the button.
+	 *
+	 * - `'default'`: For normal text-label buttons, unless it is a toggle button.
+	 * - `'compact'`: For toggle buttons, icon buttons, and buttons when used in context of either.
+	 * - `'small'`: For icon buttons associated with more advanced or auxiliary features.
+	 *
+	 * @default "default"
+	 */
+	size?: 'default' | 'compact' | 'small';
+
+	/**
+	 * Whether the button is disabled.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Whether the element should be focusable even when it is disabled.
+	 *
+	 * @default true
+	 */
+	focusableWhenDisabled?: _ButtonProps[ 'focusableWhenDisabled' ];
+
+	/**
+	 * Indicates the current "pressed" state of toggle buttons. This should only
+	 * be used with neutral minimal buttons.
+	 */
+	'aria-pressed'?: HTMLAttributes< HTMLButtonElement >[ 'aria-pressed' ];
+
+	/**
+	 * The content of the button.
+	 */
+	children?: ReactNode;
+
+	/**
+	 * Whether the button is in a loading state, such as when an action is being
+	 * performed.
+	 * @default false
+	 */
+	loading?: boolean;
+
+	/**
+	 * The text used for assistive technology to indicate the loading state.
+	 */
+	loadingAnnouncement?: string;
+}

package/src/form/primitives/field/control.tsx

@@ -0,0 +1,9 @@
+import { Field as _Field } from '@base-ui/react/field';
+import { forwardRef } from '@wordpress/element';
+import type { FieldControlProps } from './types';
+
+export const Control = forwardRef< HTMLInputElement, FieldControlProps >(
+	function Control( props, ref ) {
+		return <_Field.Control ref={ ref } { ...props } />;
+	}
+);

package/src/form/primitives/field/description.tsx

@@ -0,0 +1,18 @@
+import clsx from 'clsx';
+import { Field as _Field } from '@base-ui/react/field';
+import { forwardRef } from '@wordpress/element';
+import fieldStyles from '../../../utils/css/field.module.css';
+import type { FieldDescriptionProps } from './types';
+
+export const Description = forwardRef<
+	HTMLParagraphElement,
+	FieldDescriptionProps
+>( function Description( { className, ...restProps }, ref ) {
+	return (
+		<_Field.Description
+			ref={ ref }
+			className={ clsx( fieldStyles.description, className ) }
+			{ ...restProps }
+		/>
+	);
+} );

package/src/form/primitives/field/details.tsx

@@ -0,0 +1,36 @@
+import clsx from 'clsx';
+import { Field as _Field } from '@base-ui/react/field';
+import { forwardRef } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import fieldStyles from '../../../utils/css/field.module.css';
+import type { FieldDetailsProps } from './types';
+import { VisuallyHidden } from '../../../visually-hidden';
+
+/**
+ * A component for showing additional information about the field,
+ * styled similarly to a normal `Field.Description`.
+ * Unlike a normal description, it can include links and other semantic elements.
+ *
+ * Although this content is not associated with the field using direct semantics,
+ * it is made discoverable to screen reader users via a visually hidden description,
+ * alerting them to the presence of additional information below.
+ *
+ * If the content only includes plain text, use `Field.Description` instead,
+ * so the readout is not unnecessarily verbose for screen reader users.
+ */
+export const Details = forwardRef< HTMLDivElement, FieldDetailsProps >(
+	function Details( { className, ...restProps }, ref ) {
+		return (
+			<>
+				<_Field.Description render={ <VisuallyHidden /> }>
+					{ __( 'More details follow the field.' ) }
+				</_Field.Description>
+				<div
+					ref={ ref }
+					className={ clsx( fieldStyles.description, className ) }
+					{ ...restProps }
+				></div>
+			</>
+		);
+	}
+);

package/src/form/primitives/field/index.ts

@@ -0,0 +1,8 @@
+import { Root } from './root';
+import { Item } from './item';
+import { Label } from './label';
+import { Description } from './description';
+import { Details } from './details';
+import { Control } from './control';
+
+export { Root, Item, Label, Description, Details, Control };

package/src/form/primitives/field/item.tsx

@@ -0,0 +1,9 @@
+import { Field as _Field } from '@base-ui/react/field';
+import { forwardRef } from '@wordpress/element';
+import type { FieldItemProps } from './types';
+
+export const Item: React.ForwardRefExoticComponent<
+	FieldItemProps & React.RefAttributes< HTMLDivElement >
+> = forwardRef( function Item( props, ref ) {
+	return <_Field.Item ref={ ref } { ...props } />;
+} );