@wordpress/components 19.7.0 → 19.9.0

package/src/base-control/README.md

@@ -1,14 +1,15 @@
 # BaseControl
 
-BaseControl component is used to generate labels and help text for components handling user inputs.
+`BaseControl` is a component used to generate labels and help text for components handling user inputs.
 
 ## Usage
 
-Render a BaseControl for a textarea input:
+Render a `BaseControl` for a textarea input:
 
 ```jsx
 import { BaseControl } from '@wordpress/components';
 
+// The `id` prop is necessary to accessibly associate the label with the textarea
 const MyBaseControl = () => (
 	<BaseControl id="textarea-1" label="Text" help="Enter some text" __nextHasNoMarginBottom={ true }>
 		<textarea id="textarea-1" />
@@ -22,10 +23,10 @@ The component accepts the following props:
 
 ### id
 
-The id of the element to which labels and help text are being generated. That element should be passed as a child.
+The HTML `id` of the element (passed in as a child to `BaseControl`) to which labels and help text are being generated. This is necessary to accessibly associate the label with that element.
 
 -   Type: `String`
--   Required: Yes
+-   Required: No
 
 ### label
 
@@ -50,8 +51,7 @@ If this property is added, a help text will be generated using help property as
 
 ### className
 
-The class that will be added with "components-base-control" to the classes of the wrapper div.
-If no className is passed only components-base-control is used.
+Any other classes to add to the wrapper div.
 
 -   Type: `String`
 -   Required: No
@@ -73,8 +73,9 @@ Start opting into the new margin-free styles that will become the default in a f
 
 ## BaseControl.VisualLabel
 
-`BaseControl.VisualLabel` component is used to render a purely visual label inside a `BaseControl` component.
-It should only be used in cases where the children being rendered inside BaseControl are already properly labeled, e.g., a button, but we want an additional visual label for that section equivalent to the labels BaseControl would otherwise use if the label prop was passed.
+`BaseControl.VisualLabel` is used to render a purely visual label inside a `BaseControl` component.
+
+It should only be used in cases where the children being rendered inside BaseControl are already accessibly labeled, e.g., a button, but we want an additional visual label for that section equivalent to the labels `BaseControl` would otherwise use if the `label` prop was passed.
 
 ## Usage
 
@@ -82,7 +83,7 @@ It should only be used in cases where the children being rendered inside BaseCon
 import { BaseControl } from '@wordpress/components';
 
 const MyBaseControl = () => (
-	<BaseControl help="Pressing the Select an author button will open a modal that allows an advanced mechanism for author selection">
+	<BaseControl help="This button is already accessibly labeled.">
 		<BaseControl.VisualLabel>Author</BaseControl.VisualLabel>
 		<Button>Select an author</Button>
 	</BaseControl>
@@ -93,8 +94,7 @@ const MyBaseControl = () => (
 
 #### className
 
-The class that will be added with `components-base-control__label` to the classes of the wrapper div.
-If no className is passed only `components-base-control__label` is used.
+Any other classes to add to the wrapper div.
 
 -   Type: `String`
 -   Required: No

package/src/base-control/index.tsx

@@ -0,0 +1,124 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+import type { FunctionComponent } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { VisuallyHidden } from '../visually-hidden';
+import type { BaseControlProps, BaseControlVisualLabelProps } from './types';
+import {
+	Wrapper,
+	StyledField,
+	StyledLabel,
+	StyledHelp,
+	StyledVisualLabel,
+} from './styles/base-control-styles';
+
+/**
+ * `BaseControl` is a component used to generate labels and help text for components handling user inputs.
+ *
+ * @example
+ * // Render a `BaseControl` for a textarea input
+ * import { BaseControl } from '@wordpress/components';
+ *
+ * // The `id` prop is necessary to accessibly associate the label with the textarea
+ * const MyBaseControl = () => (
+ *   <BaseControl id="textarea-1" label="Text" help="Enter some text" __nextHasNoMarginBottom={ true }>
+ *     <textarea id="textarea-1" />
+ *   </BaseControl>
+ * );
+ */
+export const BaseControl = ( {
+	__nextHasNoMarginBottom = false,
+	id,
+	label,
+	hideLabelFromVision = false,
+	help,
+	className,
+	children,
+}: BaseControlProps ) => {
+	return (
+		<Wrapper
+			className={ classnames( 'components-base-control', className ) }
+		>
+			<StyledField
+				className="components-base-control__field"
+				// TODO: Official deprecation for this should start after all internal usages have been migrated
+				__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+			>
+				{ label &&
+					id &&
+					( hideLabelFromVision ? (
+						<VisuallyHidden as="label" htmlFor={ id }>
+							{ label }
+						</VisuallyHidden>
+					) : (
+						<StyledLabel
+							className="components-base-control__label"
+							htmlFor={ id }
+						>
+							{ label }
+						</StyledLabel>
+					) ) }
+				{ label &&
+					! id &&
+					( hideLabelFromVision ? (
+						<VisuallyHidden as="label">{ label }</VisuallyHidden>
+					) : (
+						<BaseControl.VisualLabel>
+							{ label }
+						</BaseControl.VisualLabel>
+					) ) }
+				{ children }
+			</StyledField>
+			{ !! help && (
+				<StyledHelp
+					id={ id ? id + '__help' : undefined }
+					className="components-base-control__help"
+					__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+				>
+					{ help }
+				</StyledHelp>
+			) }
+		</Wrapper>
+	);
+};
+
+/**
+ * `BaseControl.VisualLabel` is used to render a purely visual label inside a `BaseControl` component.
+ *
+ * It should only be used in cases where the children being rendered inside `BaseControl` are already accessibly labeled,
+ * e.g., a button, but we want an additional visual label for that section equivalent to the labels `BaseControl` would
+ * otherwise use if the `label` prop was passed.
+ *
+ * @example
+ * import { BaseControl } from '@wordpress/components';
+ *
+ * const MyBaseControl = () => (
+ * 	<BaseControl help="This button is already accessibly labeled.">
+ * 		<BaseControl.VisualLabel>Author</BaseControl.VisualLabel>
+ * 		<Button>Select an author</Button>
+ * 	</BaseControl>
+ * );
+ */
+export const VisualLabel: FunctionComponent< BaseControlVisualLabelProps > = ( {
+	className,
+	children,
+} ) => {
+	return (
+		<StyledVisualLabel
+			className={ classnames(
+				'components-base-control__label',
+				className
+			) }
+		>
+			{ children }
+		</StyledVisualLabel>
+	);
+};
+BaseControl.VisualLabel = VisualLabel;
+
+export default BaseControl;

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

@@ -0,0 +1,80 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '..';
+import Button from '../../button';
+
+const meta: ComponentMeta< typeof BaseControl > = {
+	title: 'Components/BaseControl',
+	component: BaseControl,
+	argTypes: {
+		children: { control: { type: null } },
+		help: { control: { type: 'text' } },
+		label: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const BaseControlWithTextarea: ComponentStory< typeof BaseControl > = ( {
+	id,
+	...props
+} ) => {
+	return (
+		<BaseControl id={ id } { ...props }>
+			<textarea style={ { display: 'block' } } id={ id } />
+		</BaseControl>
+	);
+};
+
+export const Default: ComponentStory<
+	typeof BaseControl
+> = BaseControlWithTextarea.bind( {} );
+Default.args = {
+	__nextHasNoMarginBottom: true,
+	id: 'textarea-default-1',
+	label: 'Label text',
+};
+
+export const WithHelpText = BaseControlWithTextarea.bind( {} );
+WithHelpText.args = {
+	...Default.args,
+	id: 'textarea-with-help-text-1',
+	help: 'Help text adds more explanation.',
+};
+
+/**
+ * `BaseControl.VisualLabel` is used to render a purely visual label inside a `BaseControl` component.
+ *
+ * It should only be used in cases where the children being rendered inside `BaseControl` are already accessibly labeled,
+ * e.g., a button, but we want an additional visual label for that section equivalent to the labels `BaseControl` would
+ * otherwise use if the `label` prop was passed.
+ */
+export const WithVisualLabel: ComponentStory< typeof BaseControl > = (
+	props
+) => {
+	BaseControl.VisualLabel.displayName = 'BaseControl.VisualLabel';
+
+	return (
+		<BaseControl { ...props }>
+			<BaseControl.VisualLabel>Visual label</BaseControl.VisualLabel>
+			<div>
+				<Button variant="secondary">Select an author</Button>
+			</div>
+		</BaseControl>
+	);
+};
+WithVisualLabel.args = {
+	...Default.args,
+	help: 'This button is already accessibly labeled.',
+	id: undefined,
+	label: undefined,
+};

package/src/base-control/types.ts

@@ -0,0 +1,42 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+export type BaseControlProps = {
+	/**
+	 * Start opting into the new margin-free styles that will become the default in a future version.
+	 *
+	 * @default false
+	 */
+	__nextHasNoMarginBottom?: boolean;
+	/**
+	 * The HTML `id` of the element (passed in as a child to `BaseControl`) to which labels and help text are being generated.
+	 * This is necessary to accessibly associate the label with that element.
+	 */
+	id?: string;
+	/**
+	 * If this property is added, a help text will be generated using help property as the content.
+	 */
+	help?: ReactNode;
+	/**
+	 * If this property is added, a label will be generated using label property as the content.
+	 */
+	label?: ReactNode;
+	/**
+	 * If true, the label will only be visible to screen readers.
+	 *
+	 * @default false
+	 */
+	hideLabelFromVision?: boolean;
+	className?: string;
+	/**
+	 * The content to be displayed within the `BaseControl`.
+	 */
+	children: ReactNode;
+};
+
+export type BaseControlVisualLabelProps = {
+	className?: string;
+	children: ReactNode;
+};

package/src/border-box-control/border-box-control/README.md

@@ -0,0 +1,178 @@
+# BorderBoxControl
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+<br />
+
+This component provides users with the ability to configure a single "flat"
+border or separate borders per side.
+
+## Development guidelines
+
+The `BorderBoxControl` effectively has two view states. The first, a "linked"
+view, allows configuration of a flat border via a single `BorderControl`.
+The second, a "split" view, contains a `BorderControl` for each side
+as well as a visualizer for the currently selected borders. Each view also
+contains a button to toggle between the two.
+
+When switching from the "split" view to "linked", if the individual side
+borders are not consistent, the "linked" view will display any border properties
+selections that are consistent while showing a mixed state for those that
+aren't. For example, if all borders had the same color and style but different
+widths, then the border dropdown in the "linked" view's `BorderControl` would
+show that consistent color and style but the "linked" view's width input would
+show "Mixed" placeholder text.
+
+## Usage
+
+```jsx
+import { __experimentalBorderBoxControl as BorderBoxControl } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+
+const colors = [
+	{ name: 'Blue 20', color: '#72aee6' },
+	// ...
+];
+
+const MyBorderBoxControl = () => {
+	const defaultBorder = {
+		color: '#72aee6',
+		style: 'dashed',
+		width: '1px',
+	};
+	const [ borders, setBorders ] = useState( {
+		top: defaultBorder,
+		right: defaultBorder,
+		bottom: defaultBorder,
+		left: defaultBorder,
+	} );
+	const onChange = ( newBorders ) => setBorders( newBorders );
+
+	return (
+		<BorderBoxControl
+			colors={ colors }
+			label={ __( 'Borders' ) }
+			onChange={ onChange }
+			value={ borders }
+		/>
+	);
+};
+```
+
+If you're using this component outside the editor, you can
+[ensure `Tooltip` positioning](/packages/components/README.md#popovers-and-tooltips)
+for the `BorderBoxControl`'s color and style options, by rendering your
+`BorderBoxControl` with a `Popover.Slot` further up the element tree and within
+a `SlotFillProvider` overall.
+
+## Props
+
+### `colors`: `Array`
+
+An array of color definitions. This may also be a multi-dimensional array where
+colors are organized by multiple origins.
+
+Each color may be an object containing a `name` and `color` value.
+
+- Required: No
+
+### `disableCustomColors`: `boolean`
+
+This toggles the ability to choose custom colors.
+
+- Required: No
+
+### `enableAlpha`: `boolean`
+
+This controls whether the alpha channel will be offered when selecting
+custom colors.
+
+- Required: No
+
+### `enableStyle`: `boolean`
+
+This controls whether to support border style selections.
+
+- Required: No
+- Default: `true`
+
+### `hideLabelFromVision`: `boolean`
+
+Provides control over whether the label will only be visible to screen readers.
+
+- Required: No
+
+### `label`: `string`
+
+If provided, a label will be generated using this as the content.
+
+_Whether it is visible only to screen readers is controlled via
+`hideLabelFromVision`._
+
+- Required: No
+
+### `onChange`: `( value?: Object ) => void`
+
+A callback function invoked when any border value is changed. The value received
+may be a "flat" border object, one that has properties defining individual side
+borders, or `undefined`.
+
+_Note: The will be `undefined` if a user clears all borders._
+
+- Required: Yes
+
+### `popoverClassNames`: `Object`
+
+An object defining CSS classnames for all the inner `BorderControl` popover
+content.
+
+Example:
+```js
+{
+	linked: 'linked-border-popover-content',
+	top: 'top-border-popover-content',
+	right: 'right-border-popover-content',
+	bottom: 'bottom-border-popover-content',
+	left: 'left-border-popover-content',
+}
+```
+
+By default, popovers are displayed relative to the button that initiated the popover. By supplying classnames for each individual popover, it is possible to add styling rules to align the popover positions to an unrelated design element, for example, the sidebar inspector in the block editor.
+
+- Required: No
+
+### `value`: `Object`
+
+An object representing the current border configuration.
+
+This may be a "flat" border where the object has `color`, `style`, and `width`
+properties or a "split" border which defines the previous properties but for
+each side; `top`, `right`, `bottom`, and `left`.
+
+Examples:
+```js
+const flatBorder = { color: '#72aee6', style: 'solid', width: '1px' };
+const splitBorders = {
+	top: { color: '#72aee6', style: 'solid', width: '1px' },
+	right: { color: '#e65054', style: 'dashed', width: '2px' },
+	bottom: { color: '#68de7c', style: 'solid', width: '1px' },
+	left: { color: '#f2d675', style: 'dotted', width: '1em' },
+};
+```
+
+- Required: No
+
+### `__experimentalHasMultipleOrigins`: `boolean`
+
+This is passed on to the color related sub-components which need to be made
+aware of whether the colors prop contains multiple origins.
+
+- Required: No
+
+### `__experimentalIsRenderedInSidebar`: `boolean`
+
+This is passed on to the color related sub-components so they may render more
+effectively when used within a sidebar.
+
+- Required: No

package/src/border-box-control/border-box-control/component.tsx

@@ -0,0 +1,123 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import BorderBoxControlLinkedButton from '../border-box-control-linked-button';
+import BorderBoxControlSplitControls from '../border-box-control-split-controls';
+import { BorderControl } from '../../border-control';
+import { HStack } from '../../h-stack';
+import { StyledLabel } from '../../base-control/styles/base-control-styles';
+import { View } from '../../view';
+import { VisuallyHidden } from '../../visually-hidden';
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { useBorderBoxControl } from './hook';
+
+import type { BorderBoxControlProps } from '../types';
+import type { LabelProps } from '../../border-control/types';
+
+const BorderLabel = ( props: LabelProps ) => {
+	const { label, hideLabelFromVision } = props;
+
+	if ( ! label ) {
+		return null;
+	}
+
+	return hideLabelFromVision ? (
+		<VisuallyHidden as="label">{ label }</VisuallyHidden>
+	) : (
+		<StyledLabel>{ label }</StyledLabel>
+	);
+};
+
+const BorderBoxControl = (
+	props: WordPressComponentProps< BorderBoxControlProps, 'div' >,
+	forwardedRef: React.ForwardedRef< any >
+) => {
+	const {
+		className,
+		colors,
+		disableCustomColors,
+		enableAlpha,
+		enableStyle,
+		hasMixedBorders,
+		hideLabelFromVision,
+		isLinked,
+		label,
+		linkedControlClassName,
+		linkedValue,
+		onLinkedChange,
+		onSplitChange,
+		popoverClassNames,
+		splitValue,
+		toggleLinked,
+		__experimentalHasMultipleOrigins,
+		__experimentalIsRenderedInSidebar,
+		...otherProps
+	} = useBorderBoxControl( props );
+
+	return (
+		<View className={ className } { ...otherProps } ref={ forwardedRef }>
+			<BorderLabel
+				label={ label }
+				hideLabelFromVision={ hideLabelFromVision }
+			/>
+			<HStack alignment={ 'start' } expanded={ true } spacing={ 0 }>
+				{ isLinked ? (
+					<BorderControl
+						className={ linkedControlClassName }
+						colors={ colors }
+						disableCustomColors={ disableCustomColors }
+						enableAlpha={ enableAlpha }
+						enableStyle={ enableStyle }
+						onChange={ onLinkedChange }
+						placeholder={
+							hasMixedBorders ? __( 'Mixed' ) : undefined
+						}
+						popoverContentClassName={ popoverClassNames?.linked }
+						shouldSanitizeBorder={ false } // This component will handle that.
+						value={ linkedValue }
+						withSlider={ true }
+						width={ '110px' }
+						__experimentalHasMultipleOrigins={
+							__experimentalHasMultipleOrigins
+						}
+						__experimentalIsRenderedInSidebar={
+							__experimentalIsRenderedInSidebar
+						}
+					/>
+				) : (
+					<BorderBoxControlSplitControls
+						colors={ colors }
+						disableCustomColors={ disableCustomColors }
+						enableAlpha={ enableAlpha }
+						enableStyle={ enableStyle }
+						onChange={ onSplitChange }
+						popoverClassNames={ popoverClassNames }
+						value={ splitValue }
+						__experimentalHasMultipleOrigins={
+							__experimentalHasMultipleOrigins
+						}
+						__experimentalIsRenderedInSidebar={
+							__experimentalIsRenderedInSidebar
+						}
+					/>
+				) }
+				<BorderBoxControlLinkedButton
+					onClick={ toggleLinked }
+					isLinked={ isLinked }
+				/>
+			</HStack>
+		</View>
+	);
+};
+
+const ConnectedBorderBoxControl = contextConnect(
+	BorderBoxControl,
+	'BorderBoxControl'
+);
+
+export default ConnectedBorderBoxControl;