@wordpress/components 21.2.0 → 22.0.0

package/src/text-control/stories/index.tsx

@@ -17,12 +17,11 @@ const meta: ComponentMeta< typeof TextControl > = {
 	component: TextControl,
 	title: 'Components/TextControl',
 	argTypes: {
-		onChange: {
-			action: 'onChange',
-		},
-		value: {
-			control: { type: null },
-		},
+		help: { control: { type: 'text' } },
+		label: { control: { type: 'text' } },
+		type: { control: { type: 'text' } },
+		onChange: { action: 'onChange' },
+		value: { control: { type: null } },
 	},
 	parameters: {
 		controls: {

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

@@ -50,9 +50,7 @@ describe( 'TextHighlight', () => {
 			expect( highlightedEls ).toHaveLength( 2 );
 
 			highlightedEls.forEach( ( el ) => {
-				expect( el.textContent ).toEqual(
-					expect.stringContaining( highlight )
-				);
+				expect( el ).toHaveTextContent( highlight );
 			} );
 		} );
 

package/src/theme/README.md

@@ -0,0 +1,34 @@
+# Theme
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+`Theme` allows defining theme variables for components in the `@wordpress/components` package.
+
+Multiple `Theme` components can be nested in order to override specific theme variables.
+
+## Usage
+
+```jsx
+import { __experimentalTheme as Theme } from '@wordpress/components';
+
+const Example = () => {
+	return (
+		<Theme accent="red">
+			<Button variant="primary">I'm red</Button>
+			<Theme accent="blue">
+				<Button variant="primary">I'm blue</Button>
+			</Theme>
+		</Theme>
+	);
+};
+```
+
+## Props
+
+### `accent`: `string`
+
+Used to set the accent color (used by components as the primary color). If an accent color is not defined, the default fallback value is the original WP Admin main theme color. No all valid CSS color syntaxes are supported — in particular, keywords (like `'currentcolor'`, `'inherit'`, `'initial'`, `'revert'`, `'unset'`...) and CSS custom properties (e.g. `var(--my-custom-property)`) are _not_ supported values for this property.
+
+-   Required: No

package/src/theme/index.tsx

@@ -0,0 +1,51 @@
+/**
+ * External dependencies
+ */
+import { colord, extend } from 'colord';
+import a11yPlugin from 'colord/plugins/a11y';
+import namesPlugin from 'colord/plugins/names';
+
+/**
+ * Internal dependencies
+ */
+import type { ThemeProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+import { Wrapper } from './styles';
+
+extend( [ namesPlugin, a11yPlugin ] );
+
+/**
+ * `Theme` allows defining theme variables for components in the `@wordpress/components` package.
+ *
+ * Multiple `Theme` components can be nested in order to override specific theme variables.
+ *
+ *
+ * @example
+ * ```jsx
+ * import { __experimentalTheme as Theme } from '@wordpress/components';
+ *
+ * const Example = () => {
+ *   return (
+ *     <Theme accent="red">
+ *       <Button variant="primary">I'm red</Button>
+ *       <Theme accent="blue">
+ *         <Button variant="primary">I'm blue</Button>
+ *       </Theme>
+ *     </Theme>
+ *   );
+ * };
+ * ```
+ */
+function Theme( props: WordPressComponentProps< ThemeProps, 'div', true > ) {
+	const { accent } = props;
+	if ( accent && ! colord( accent ).isValid() ) {
+		// eslint-disable-next-line no-console
+		console.warn(
+			`wp.components.Theme: "${ accent }" is not a valid color value for the 'accent' prop.`
+		);
+	}
+
+	return <Wrapper { ...props } />;
+}
+
+export default Theme;

package/src/theme/stories/index.tsx

@@ -0,0 +1,47 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import Theme from '../index';
+import Button from '../../button';
+
+const meta: ComponentMeta< typeof Theme > = {
+	component: Theme,
+	title: 'Components (Experimental)/Theme',
+	argTypes: {
+		accent: { control: { type: 'color' } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof Theme > = ( args ) => (
+	<Theme { ...args }>
+		<Button variant="primary">Hello</Button>
+	</Theme>
+);
+
+export const Default = Template.bind( {} );
+Default.args = {};
+
+export const Nested: ComponentStory< typeof Theme > = ( args ) => (
+	<Theme accent="tomato">
+		<Button variant="primary">Outer theme (hardcoded)</Button>
+
+		<Theme { ...args }>
+			<Button variant="primary">
+				Inner theme (set via Storybook controls)
+			</Button>
+		</Theme>
+	</Theme>
+);
+Nested.args = {
+	accent: 'blue',
+};

package/src/theme/styles.ts

@@ -0,0 +1,28 @@
+/**
+ * External dependencies
+ */
+import { colord } from 'colord';
+import styled from '@emotion/styled';
+import { css } from '@emotion/react';
+
+/**
+ * Internal dependencies
+ */
+import type { ThemeProps } from './types';
+
+const accentColor = ( { accent }: ThemeProps ) =>
+	accent
+		? css`
+				--wp-components-color-accent: ${ accent };
+				--wp-components-color-accent-darker-10: ${ colord( accent )
+					.darken( 0.1 )
+					.toHex() };
+				--wp-components-color-accent-darker-20: ${ colord( accent )
+					.darken( 0.2 )
+					.toHex() };
+		  `
+		: undefined;
+
+export const Wrapper = styled.div< ThemeProps >`
+	${ accentColor }
+`;

package/src/theme/test/index.tsx

@@ -0,0 +1,101 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+import type { ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import Theme from '../';
+
+type MyThemableComponentProps = {
+	children: ReactNode;
+};
+
+const MyThemableComponent = ( props: MyThemableComponentProps ) => {
+	return (
+		<div
+			{ ...props }
+			style={ {
+				color: 'var(--wp-components-color-accent)',
+			} }
+		/>
+	);
+};
+
+describe( 'Theme', () => {
+	describe( 'accent color', () => {
+		it( 'it does not define the accent color (and its variations) as a CSS variable when the `accent` prop is undefined', () => {
+			render(
+				<Theme>
+					<MyThemableComponent>Inner</MyThemableComponent>
+				</Theme>
+			);
+
+			const inner = screen.getByText( 'Inner' );
+
+			if ( inner?.parentElement === null ) {
+				throw new Error(
+					'Somehow the `Theme` component does not render a DOM element?'
+				);
+			}
+
+			const innerElementStyles = window.getComputedStyle(
+				inner?.parentElement
+			);
+
+			expect(
+				innerElementStyles.getPropertyValue(
+					'--wp-components-color-accent'
+				)
+			).toBe( '' );
+
+			expect(
+				innerElementStyles.getPropertyValue(
+					'--wp-components-color-accent-darker-10'
+				)
+			).toBe( '' );
+
+			expect(
+				innerElementStyles.getPropertyValue(
+					'--wp-components-color-accent-darker-20'
+				)
+			).toBe( '' );
+		} );
+
+		it( 'it defines the accent color (and its variations) as a CSS variable', () => {
+			render(
+				<Theme accent="#123abc">
+					<MyThemableComponent>Inner</MyThemableComponent>
+				</Theme>
+			);
+
+			const inner = screen.getByText( 'Inner' );
+
+			expect( inner?.parentElement ).toHaveStyle( {
+				'--wp-components-color-accent': '#123abc',
+				'--wp-components-color-accent-darker-10': '#0e2c8d',
+				'--wp-components-color-accent-darker-20': '#091d5f',
+			} );
+		} );
+
+		describe( 'unsupported values', () => {
+			it.each( [
+				// Keywords
+				'currentcolor',
+				'initial',
+				'reset',
+				'inherit',
+				'revert',
+				'unset',
+				// CSS Custom properties
+				'var( --my-variable )',
+			] )( 'should warn when the value is "%s"', ( accentValue ) => {
+				render( <Theme accent={ accentValue } /> );
+
+				expect( console ).toHaveWarned();
+			} );
+		} );
+	} );
+} );

package/src/theme/types.ts

@@ -0,0 +1,21 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+export type ThemeProps = {
+	/**
+	 * Used to set the accent color (used by components as the primary color).
+	 *
+	 * If an accent color is not defined, the default fallback value is the original
+	 * WP Admin main theme color. No all valid CSS color syntaxes are supported —
+	 * in particular, keywords (like `'currentcolor'`, `'inherit'`, `'initial'`,
+	 * `'revert'`, `'unset'`...) and CSS custom properties (e.g.
+	 * `var(--my-custom-property)`) are _not_ supported values for this property.
+	 */
+	accent?: string;
+	/**
+	 * The children elements.
+	 */
+	children?: ReactNode;
+};

package/src/toggle-control/README.md

@@ -44,14 +44,16 @@ If this property is added, a label will be generated using label property as the
 ### help
 
 If this property is added, a help text will be generated using help property as the content.
+For controlled components the `help` prop can also be a function which will return a help text
+dynamically depending on the boolean `checked` parameter.
 
--   Type: `String|WPElement`
+-   Type: `String|WPElement|Function`
 -   Required: No
 
 ### checked
 
 If checked is true the toggle will be checked. If checked is false the toggle will be unchecked.
-If no value is passed the toggle will be unchecked.
+If no value is passed the toggle will be an uncontrolled component with unchecked initial value.
 
 -   Type: `Boolean`
 -   Required: No
@@ -74,5 +76,5 @@ A function that receives the checked state (boolean) as input.
 
 The class that will be added with `components-base-control` and `components-toggle-control` to the classes of the wrapper div. If no className is passed only `components-base-control` and `components-toggle-control` are used.
 
-Type: String
-Required: No
+-		Type: `String`
+-		Required: No

package/src/toggle-control/index.tsx

@@ -64,8 +64,19 @@ export function ToggleControl( {
 
 	let describedBy, helpLabel;
 	if ( help ) {
-		describedBy = id + '__help';
-		helpLabel = typeof help === 'function' ? help( checked ) : help;
+		if ( typeof help === 'function' ) {
+			// `help` as a function works only for controlled components where
+			// `checked` is passed down from parent component. Uncontrolled
+			// component can show only a static help label.
+			if ( checked !== undefined ) {
+				helpLabel = help( checked );
+			}
+		} else {
+			helpLabel = help;
+		}
+		if ( helpLabel ) {
+			describedBy = id + '__help';
+		}
 	}
 
 	return (

package/src/toggle-control/types.ts

@@ -13,10 +13,8 @@ export type ToggleControlProps = Pick<
 	FormToggleProps,
 	'checked' | 'disabled'
 > &
-	Pick<
-		BaseControlProps,
-		'__nextHasNoMarginBottom' | 'help' | 'className'
-	> & {
+	Pick< BaseControlProps, '__nextHasNoMarginBottom' | 'className' > & {
+		help?: ReactNode | ( ( checked: boolean ) => ReactNode );
 		/**
 		 * The label for the toggle.
 		 */

package/src/toggle-group-control/stories/index.tsx

@@ -124,11 +124,11 @@ WithIcons.args = {
 };
 
 /**
- * A borderless style may be preferred in some contexts.
+ * When the `isDeselectable` prop is true, the option can be deselected by clicking on it again.
  */
-export const Borderless: ComponentStory< typeof ToggleGroupControl > =
+export const Deselectable: ComponentStory< typeof ToggleGroupControl > =
 	Template.bind( {} );
-Borderless.args = {
+Deselectable.args = {
 	...WithIcons.args,
-	__experimentalIsBorderless: true,
+	isDeselectable: true,
 };