@wordpress/components 19.15.0 → 19.16.0

package/src/scroll-lock/stories/index.tsx

@@ -0,0 +1,96 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../../button';
+import ScrollLock from '..';
+
+const meta: ComponentMeta< typeof ScrollLock > = {
+	component: ScrollLock,
+	title: 'Components/ScrollLock',
+	parameters: {
+		controls: { hideNoControlsWarning: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+function StripedBackground( props: { children: ReactNode } ) {
+	return (
+		<div
+			style={ {
+				backgroundColor: '#fff',
+				backgroundImage:
+					'linear-gradient(transparent 50%, rgba(0, 0, 0, 0.05) 50%)',
+				backgroundSize: '50px 50px',
+				height: 3000,
+				position: 'relative',
+			} }
+			{ ...props }
+		/>
+	);
+}
+
+function ToggleContainer( props: { children: ReactNode } ) {
+	const { children } = props;
+	return (
+		<div
+			style={ {
+				position: 'sticky',
+				top: 0,
+				padding: 40,
+				display: 'flex',
+				justifyContent: 'center',
+				textAlign: 'center',
+			} }
+		>
+			<div>{ children }</div>
+		</div>
+	);
+}
+
+export const Default: ComponentStory< typeof ScrollLock > = () => {
+	const [ isScrollLocked, setScrollLocked ] = useState( false );
+	const toggleLock = () => setScrollLocked( ! isScrollLocked );
+
+	return (
+		<div style={ { height: 1000 } }>
+			<div
+				style={ {
+					overflow: 'auto',
+					height: 240,
+					border: '1px solid lightgray',
+				} }
+			>
+				<StripedBackground>
+					<div>
+						Start scrolling down. Once you scroll to the end of this
+						container with the stripes, the rest of the page will
+						continue scrolling. <code>ScrollLock</code> prevents
+						this &quot;scroll bleed&quot; from happening.
+					</div>
+					<ToggleContainer>
+						<Button variant="primary" onClick={ toggleLock }>
+							Toggle Scroll Lock
+						</Button>
+						{ isScrollLocked && <ScrollLock /> }
+						<p>
+							Scroll locked:{ ' ' }
+							<strong>{ isScrollLocked ? 'Yes' : 'No' }</strong>
+						</p>
+					</ToggleContainer>
+				</StripedBackground>
+			</div>
+		</div>
+	);
+};

package/src/scroll-lock/test/index.tsx

@@ -0,0 +1,26 @@
+/**
+ * External dependencies
+ */
+import { render } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import ScrollLock from '..';
+
+describe( 'scroll-lock', () => {
+	const lockingClassName = 'lockscroll';
+
+	it( 'locks when mounted', () => {
+		expect( document.documentElement ).not.toHaveClass( lockingClassName );
+		render( <ScrollLock /> );
+		expect( document.documentElement ).toHaveClass( lockingClassName );
+	} );
+
+	it( 'unlocks when unmounted', () => {
+		const { unmount } = render( <ScrollLock /> );
+		expect( document.documentElement ).toHaveClass( lockingClassName );
+		unmount();
+		expect( document.documentElement ).not.toHaveClass( lockingClassName );
+	} );
+} );

package/src/select-control/index.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { isEmpty } from 'lodash';
 import classNames from 'classnames';
 import type { ChangeEvent, FocusEvent, ForwardedRef } from 'react';
 
@@ -59,7 +58,7 @@ function UnforwardedSelectControl(
 	const helpId = help ? `${ id }__help` : undefined;
 
 	// Disable reason: A select with an onchange throws a warning.
-	if ( isEmpty( options ) && ! children ) return null;
+	if ( ! options?.length && ! children ) return null;
 
 	const handleOnBlur = ( event: FocusEvent< HTMLSelectElement > ) => {
 		onBlur( event );

package/src/select-control/styles/select-control-styles.ts

@@ -10,7 +10,8 @@ import styled from '@emotion/styled';
 import { COLORS, rtl } from '../../utils';
 import type { SelectControlProps } from '../types';
 
-interface SelectProps extends Pick< SelectControlProps, 'disabled' > {
+interface SelectProps
+	extends Pick< SelectControlProps, '__next36pxDefaultSize' | 'disabled' > {
 	// Using `selectSize` instead of `size` to avoid a type conflict with the
 	// `size` HTML attribute of the `select` element.
 	selectSize?: SelectControlProps[ 'size' ];
@@ -45,11 +46,14 @@ const fontSizeStyles = ( { selectSize = 'default' }: SelectProps ) => {
 	`;
 };
 
-const sizeStyles = ( { selectSize = 'default' }: SelectProps ) => {
+const sizeStyles = ( {
+	__next36pxDefaultSize,
+	selectSize = 'default',
+}: SelectProps ) => {
 	const sizes = {
 		default: {
-			height: 30,
-			minHeight: 30,
+			height: 36,
+			minHeight: 36,
 			paddingTop: 0,
 			paddingBottom: 0,
 		},
@@ -67,16 +71,28 @@ const sizeStyles = ( { selectSize = 'default' }: SelectProps ) => {
 		},
 	};
 
-	const style = sizes[ selectSize ];
+	if ( ! __next36pxDefaultSize ) {
+		sizes.default = {
+			height: 30,
+			minHeight: 30,
+			paddingTop: 0,
+			paddingBottom: 0,
+		};
+	}
+
+	const style = sizes[ selectSize ] || sizes.default;
 
 	return css( style );
 };
 
-const sizePaddings = ( { selectSize = 'default' }: SelectProps ) => {
+const sizePaddings = ( {
+	__next36pxDefaultSize,
+	selectSize = 'default',
+}: SelectProps ) => {
 	const sizes = {
 		default: {
-			paddingLeft: 8,
-			paddingRight: 24,
+			paddingLeft: 16,
+			paddingRight: 32,
 		},
 		small: {
 			paddingLeft: 8,
@@ -87,7 +103,15 @@ const sizePaddings = ( { selectSize = 'default' }: SelectProps ) => {
 			paddingRight: 32,
 		},
 	};
-	return rtl( sizes[ selectSize ] );
+
+	if ( ! __next36pxDefaultSize ) {
+		sizes.default = {
+			paddingLeft: 8,
+			paddingRight: 24,
+		};
+	}
+
+	return rtl( sizes[ selectSize ] || sizes.default );
 };
 
 // TODO: Resolve need to use &&& to increase specificity

package/src/select-control/types.ts

@@ -12,6 +12,7 @@ import type { BaseControlProps } from '../base-control/types';
 export interface SelectControlProps
 	extends Pick<
 			InputBaseProps,
+			| '__next36pxDefaultSize'
 			| 'disabled'
 			| 'hideLabelFromVision'
 			| 'label'

package/src/shortcut/{index.js → index.tsx}

@@ -1,15 +1,11 @@
-/** @typedef {string | { display: string, ariaLabel: string }} Shortcut */
 /**
- * @typedef Props
- * @property {Shortcut} shortcut    Shortcut configuration
- * @property {string}   [className] Classname
+ * Internal dependencies
  */
+import type { ShortcutProps } from './types';
+
+function Shortcut( props: ShortcutProps ) {
+	const { shortcut, className } = props;
 
-/**
- * @param {Props} props Props
- * @return {JSX.Element | null} Element
- */
-function Shortcut( { shortcut, className } ) {
 	if ( ! shortcut ) {
 		return null;
 	}

package/src/shortcut/test/__snapshots__/index.tsx.snap

@@ -0,0 +1,15 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Shortcut renders passed className 1`] = `
+<span
+  class="my-class"
+>
+  shortcut text
+</span>
+`;
+
+exports[`Shortcut renders the shortcut display text when a string is passed as the shortcut 1`] = `
+<span>
+  shortcut text
+</span>
+`;

package/src/shortcut/test/index.tsx

@@ -0,0 +1,41 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import Shortcut from '..';
+
+describe( 'Shortcut', () => {
+	it( 'does not render anything if no shortcut prop is provided', () => {
+		const { container } = render( <Shortcut /> );
+		expect( container.firstChild ).toBe( null );
+	} );
+
+	it( 'renders the shortcut display text when a string is passed as the shortcut', () => {
+		render( <Shortcut shortcut="shortcut text" /> );
+		expect( screen.getByText( 'shortcut text' ) ).toMatchSnapshot();
+	} );
+
+	it( 'renders the shortcut display text and aria-label when an object is passed as the shortcut with the correct properties', () => {
+		render(
+			<Shortcut
+				shortcut={ {
+					display: 'shortcut text',
+					ariaLabel: 'shortcut label',
+				} }
+			/>
+		);
+
+		expect( screen.getByLabelText( 'shortcut label' ) ).toHaveTextContent(
+			'shortcut text'
+		);
+	} );
+
+	it( 'renders passed className', () => {
+		render( <Shortcut shortcut="shortcut text" className="my-class" /> );
+		expect( screen.getByText( 'shortcut text' ) ).toMatchSnapshot();
+	} );
+} );

package/src/shortcut/types.ts

@@ -0,0 +1,10 @@
+export type ShortcutProps = {
+	/**
+	 * Classname to apply to the shortcut.
+	 */
+	className?: string;
+	/**
+	 * Shortcut configuration
+	 */
+	shortcut?: string | { display: string; ariaLabel: string };
+};

package/src/spacer/component.tsx

@@ -23,7 +23,9 @@ function UnconnectedSpacer(
 /**
  * `Spacer` is a primitive layout component that providers inner (`padding`) or outer (`margin`) space in-between components. It can also be used to adaptively provide space within an `HStack` or `VStack`.
  *
- * `Spacer` comes with a bunch of shorthand props to adjust `margin` and `padding`. The values of these props work as a multiplier to the library's grid system (base of `4px`).
+ * `Spacer` comes with a bunch of shorthand props to adjust `margin` and `padding`. The values of these props
+ * can either be a number (which will act as a multiplier to the library's grid system base of 4px),
+ * or a literal CSS value string.
  *
  * ```jsx
  * import { Spacer } from `@wordpress/components`

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

@@ -23,6 +23,12 @@ import Button from '../../button';
 export default {
 	component: ToggleGroupControl,
 	title: 'Components (Experimental)/ToggleGroupControl',
+	argTypes: {
+		size: {
+			control: 'select',
+			options: [ 'default', '__unstable-large' ],
+		},
+	},
 	parameters: {
 		knobs: { disable: false },
 	},
@@ -33,7 +39,7 @@ const KNOBS_GROUPS = {
 	ToggleGroupControlOption: 'ToggleGroupControlOption',
 };
 
-const _default = ( { options } ) => {
+const _default = ( { options, ...props } ) => {
 	const [ value, setValue ] = useState( options[ 0 ].value );
 	const label = text(
 		`${ KNOBS_GROUPS.ToggleGroupControl }: label`,
@@ -87,6 +93,7 @@ const _default = ( { options } ) => {
 	return (
 		<View>
 			<ToggleGroupControl
+				{ ...props }
 				onChange={ setValue }
 				value={ value }
 				label={ label }
@@ -109,6 +116,7 @@ Default.args = {
 		{ value: 'right', label: 'Right' },
 		{ value: 'justify', label: 'Justify' },
 	],
+	size: 'default',
 };
 
 export const WithTooltip = _default.bind( {} );
@@ -130,10 +138,11 @@ WithAriaLabel.args = {
 	],
 };
 
-export const WithIcons = () => {
+export const WithIcons = ( props ) => {
 	const [ state, setState ] = useState();
 	return (
 		<ToggleGroupControl
+			{ ...props }
 			onChange={ setState }
 			value={ state }
 			label={ 'With icons' }
@@ -154,8 +163,11 @@ export const WithIcons = () => {
 		</ToggleGroupControl>
 	);
 };
+WithIcons.args = {
+	...Default.args,
+};
 
-export const WithReset = () => {
+export const WithReset = ( props ) => {
 	const [ alignState, setAlignState ] = useState();
 	const aligns = [ 'Left', 'Center', 'Right' ];
 	const alignOptions = aligns.map( ( key, index ) => (
@@ -172,6 +184,7 @@ export const WithReset = () => {
 	return (
 		<View>
 			<ToggleGroupControl
+				{ ...props }
 				onChange={ setAlignState }
 				value={ alignState }
 				label={ 'Toggle Group Control' }
@@ -185,3 +198,6 @@ export const WithReset = () => {
 		</View>
 	);
 };
+WithReset.args = {
+	...Default.args,
+};

package/src/toggle-group-control/test/__snapshots__/index.js.snap

@@ -28,12 +28,12 @@ exports[`ToggleGroupControl should render correctly with icons 1`] = `
   display: -webkit-inline-flex;
   display: -ms-inline-flexbox;
   display: inline-flex;
-  min-height: 36px;
   min-width: 0;
   padding: 2px;
   position: relative;
   -webkit-transition: -webkit-transform 100ms linear;
   transition: transform 100ms linear;
+  min-height: 36px;
 }
 
 @media ( prefers-reduced-motion: reduce ) {
@@ -167,7 +167,7 @@ exports[`ToggleGroupControl should render correctly with icons 1`] = `
     </div>
     <div
       aria-label="Test Toggle Group Control"
-      class="medium components-toggle-group-control emotion-6 emotion-7"
+      class="components-toggle-group-control emotion-6 emotion-7"
       data-wp-c16t="true"
       data-wp-component="ToggleGroupControl"
       id="toggle-group-control-1"
@@ -281,12 +281,12 @@ exports[`ToggleGroupControl should render correctly with text options 1`] = `
   display: -webkit-inline-flex;
   display: -ms-inline-flexbox;
   display: inline-flex;
-  min-height: 36px;
   min-width: 0;
   padding: 2px;
   position: relative;
   -webkit-transition: -webkit-transform 100ms linear;
   transition: transform 100ms linear;
+  min-height: 36px;
 }
 
 @media ( prefers-reduced-motion: reduce ) {
@@ -393,7 +393,7 @@ exports[`ToggleGroupControl should render correctly with text options 1`] = `
     </div>
     <div
       aria-label="Test Toggle Group Control"
-      class="medium components-toggle-group-control emotion-6 emotion-7"
+      class="components-toggle-group-control emotion-6 emotion-7"
       data-wp-c16t="true"
       data-wp-component="ToggleGroupControl"
       id="toggle-group-control-0"

package/src/toggle-group-control/toggle-group-control/component.tsx

@@ -47,6 +47,7 @@ function ToggleGroupControl(
 		hideLabelFromVision = false,
 		help,
 		onChange = noop,
+		size = 'default',
 		value,
 		children,
 		...otherProps
@@ -83,12 +84,11 @@ function ToggleGroupControl(
 	const classes = useMemo(
 		() =>
 			cx(
-				styles.ToggleGroupControl,
+				styles.ToggleGroupControl( { size } ),
 				isBlock && styles.block,
-				'medium',
 				className
 			),
-		[ className, cx, isBlock ]
+		[ className, cx, isBlock, size ]
 	);
 	return (
 		<BaseControl help={ help }>

package/src/toggle-group-control/toggle-group-control/styles.ts

@@ -8,19 +8,26 @@ import styled from '@emotion/styled';
  * Internal dependencies
  */
 import { CONFIG, COLORS, reduceMotion } from '../../utils';
+import type { ToggleGroupControlProps } from '../types';
 
-export const ToggleGroupControl = css`
+export const ToggleGroupControl = ( {
+	size,
+}: {
+	size: NonNullable< ToggleGroupControlProps[ 'size' ] >;
+} ) => css`
 	background: ${ COLORS.ui.background };
 	border: 1px solid;
 	border-color: ${ COLORS.ui.border };
 	border-radius: ${ CONFIG.controlBorderRadius };
 	display: inline-flex;
-	min-height: ${ CONFIG.controlHeight };
 	min-width: 0;
 	padding: 2px;
 	position: relative;
 	transition: transform ${ CONFIG.transitionDurationFastest } linear;
 	${ reduceMotion( 'transition' ) }
+
+	${ toggleGroupControlSize( size ) }
+
 	&:hover {
 		border-color: ${ COLORS.ui.borderHover };
 	}
@@ -33,6 +40,19 @@ export const ToggleGroupControl = css`
 	}
 `;
 
+export const toggleGroupControlSize = (
+	size: NonNullable< ToggleGroupControlProps[ 'size' ] >
+) => {
+	const heights = {
+		default: '36px',
+		'__unstable-large': '40px',
+	};
+
+	return css`
+		min-height: ${ heights[ size ] };
+	`;
+};
+
 export const block = css`
 	display: flex;
 	width: 100%;

package/src/toggle-group-control/toggle-group-control-option-base/styles.ts

@@ -69,7 +69,3 @@ export const ButtonContentView = styled.div`
 export const separatorActive = css`
 	background: transparent;
 `;
-
-export const medium = css`
-	min-height: ${ CONFIG.controlHeight };
-`;

package/src/toggle-group-control/types.ts

@@ -104,6 +104,12 @@ export type ToggleGroupControlProps = Omit<
 	 * using help property as the content.
 	 */
 	help?: ReactNode;
+	/**
+	 * The size variant of the control.
+	 *
+	 * @default 'default'
+	 */
+	size?: 'default' | '__unstable-large';
 };
 
 export type ToggleGroupControlContextProps = RadioStateReturn & {

package/src/tools-panel/tools-panel/README.md

@@ -30,45 +30,118 @@ however they will not be represented within, or controlled by, the `ToolsPanel`
 menu. An example scenario that benefits from this could be displaying
 introduction or help text within a panel.
 
+### ToolsPanel Layout
+
+The `ToolsPanel` has a two-column grid layout. By default, `ToolsPanelItem`
+components within the panel are styled to span both columns as this fits the
+majority of use-cases. Most non-control elements, such as help text, will be
+rendered as children of the related control's `ToolsPanelItem` and not require
+additional styling.
+
+Suppose an element is related to multiple controls (e.g. a contrast checker), or
+the panel itself (e.g. a panel description). In that case, these will be
+rendered into the panel without a wrapping `ToolsPanelItem`. They'll then only
+span a single column by default. If this is undesirable, those elements will
+likely need a small style tweak, e.g. `grid-column: 1 / -1;`
+
+The usage example below will illustrate a non-`ToolsPanelItem` description
+paragraph, controls that should display in a single row, and others spanning
+both columns.
+
 ## Usage
 
 ```jsx
+/**
+ * External dependencies
+ */
+import styled from '@emotion/styled';
+
+/**
+ * WordPress dependencies
+ */
 import {
+	__experimentalBoxControl as BoxControl,
 	__experimentalToolsPanel as ToolsPanel,
 	__experimentalToolsPanelItem as ToolsPanelItem,
+	__experimentalUnitControl as UnitControl,
 } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 
-import {
-	PaddingEdit,
-	hasPaddingValue,
-	resetPadding,
-	useIsPaddingDisabled,
-} from './padding';
+const PanelDescription = styled.div`
+	grid-column: span 2;
+`;
 
+const SingleColumnItem = styled( ToolsPanelItem )`
+	grid-column: span 1;
+`;
 
-export function DimensionPanel( props ) {
-	const isPaddingDisabled = useIsPaddingDisabled( props );
+export function DimensionPanel() {
+	const [ height, setHeight ] = useState();
+	const [ width, setWidth ] = useState();
+	const [ padding, setPadding ] = useState();
+	const [ margin, setMargin ] = useState();
 
 	const resetAll = () => {
-		// Reset attributes for all block support features in this panel.
+		setHeight( undefined );
+		setWidth( undefined );
+		setPadding( undefined );
+		setMargin( undefined );
 	};
 
 	return (
 		<ToolsPanel label={ __( 'Dimensions' ) } resetAll={ resetAll }>
-			<p>
-				Select dimensions or spacing related settings from the menu for
-				additional controls.
-			</p>
-			{ ! isPaddingDisabled && (
-				<ToolsPanelItem
-					hasValue={ () => hasPaddingValue( props ) }
+			<PanelDescription>
+				Select dimensions or spacing related settings from the
+				menu for additional controls.
+			</PanelDescription>
+			<SingleColumnItem
+				hasValue={ () => !! height }
+				label={ __( 'Height' ) }
+				onDeselect={ () => setHeight( undefined ) }
+				isShownByDefault
+			>
+				<UnitControl
+					label={ __( 'Height' ) }
+					onChange={ setHeight }
+					value={ height }
+				/>
+			</SingleColumnItem>
+			<SingleColumnItem
+				hasValue={ () => !! width }
+				label={ __( 'Width' ) }
+				onDeselect={ () => setWidth( undefined ) }
+				isShownByDefault
+			>
+				<UnitControl
+					label={ __( 'Width' ) }
+					onChange={ setWidth }
+					value={ width }
+				/>
+			</SingleColumnItem>
+			<ToolsPanelItem
+				hasValue={ () => !! padding }
+				label={ __( 'Padding' ) }
+				onDeselect={ () => setPadding( undefined ) }
+			>
+				<BoxControl
 					label={ __( 'Padding' ) }
-					onDeselect={ () => resetPadding( props ) }
-				>
-					<PaddingEdit { ...props } />
-				</ToolsPanelItem>
-			) }
+					onChange={ setPadding }
+					values={ padding }
+					allowReset={ false }
+				/>
+			</ToolsPanelItem>
+			<ToolsPanelItem
+				hasValue={ () => !! margin }
+				label={ __( 'Margin' ) }
+				onDeselect={ () => setMargin( undefined ) }
+			>
+				<BoxControl
+					label={ __( 'Margin' ) }
+					onChange={ setMargin }
+					values={ margin }
+					allowReset={ false }
+				/>
+			</ToolsPanelItem>
 		</ToolsPanel>
 	);
 }