@wordpress/components 19.15.0 → 19.16.0

package/src/divider/types.ts

@@ -9,31 +9,37 @@ import type { SeparatorProps } from 'reakit';
  */
 import type { SpaceInput } from '../ui/utils/space';
 
-export interface OwnProps {
+export type DividerProps = Omit<
+	SeparatorProps,
+	'children' | 'unstable_system' | 'orientation'
+> & {
 	/**
 	 * Adjusts all margins on the inline dimension.
+	 *
+	 * 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.
 	 */
 	margin?: SpaceInput;
-	/**
-	 * Adjusts the inline-start margin.
-	 */
-	marginStart?: SpaceInput;
 	/**
 	 * Adjusts the inline-end margin.
+	 *
+	 * 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.
 	 */
 	marginEnd?: SpaceInput;
 	/**
-	 * Divider's orientation. When using inside a flex container, you may need to make sure the divider is `stretch` aligned
-	 * in order for it to be visible.
+	 * Adjusts the inline-start margin.
+	 *
+	 * 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.
+	 */
+	marginStart?: SpaceInput;
+	/**
+	 * Divider's orientation. When using inside a flex container, you may need
+	 * to make sure the divider is `stretch` aligned in order for it to be
+	 * visible.
 	 *
 	 * @default 'horizontal'
 	 */
 	orientation?: SeparatorProps[ 'orientation' ];
-}
-
-export interface Props
-	extends Omit<
-			SeparatorProps,
-			'children' | 'unstable_system' | 'orientation'
-		>,
-		OwnProps {}
+};

package/src/draggable/README.md

@@ -1,6 +1,6 @@
 # Draggable
 
-`Draggable` is a Component that provides a way to set up a a cross-browser (including IE) customisable drag image and the transfer data for the drag event. It decouples the drag handle and the element to drag: use it by wrapping the component that will become the drag handle and providing the DOM ID of the element to drag.
+`Draggable` is a Component that provides a way to set up a cross-browser (including IE) customisable drag image and the transfer data for the drag event. It decouples the drag handle and the element to drag: use it by wrapping the component that will become the drag handle and providing the DOM ID of the element to drag.
 
 Note that the drag handle needs to declare the `draggable="true"` property and bind the `Draggable`s `onDraggableStart` and `onDraggableEnd` event handlers to its own `onDragStart` and `onDragEnd` respectively. `Draggable` takes care of the logic to setup the drag image and the transfer data, but is not concerned with creating an actual DOM element that is draggable.
 

package/src/dropdown/dropdown-content-wrapper.tsx

@@ -0,0 +1,59 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import {
+	WordPressComponentProps,
+	contextConnect,
+	useContextSystem,
+} from '../ui/context';
+import { DropdownContentWrapperDiv } from './styles';
+import type { DropdownContentWrapperProps } from './types';
+
+function UnconnectedDropdownContentWrapper(
+	props: WordPressComponentProps< DropdownContentWrapperProps, 'div', false >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const { paddingSize = 'small', ...derivedProps } = useContextSystem(
+		props,
+		'DropdownContentWrapper'
+	);
+
+	return (
+		<DropdownContentWrapperDiv
+			{ ...derivedProps }
+			paddingSize={ paddingSize }
+			ref={ forwardedRef }
+		/>
+	);
+}
+
+/**
+ * A convenience wrapper for the `renderContent` when you want to apply
+ * different padding. (Default is `paddingSize="small"`).
+ *
+ * ```jsx
+ * import {
+ *   Dropdown,
+ *   __experimentalDropdownContentWrapper as DropdownContentWrapper,
+ * } from '@wordpress/components';
+ *
+ * <Dropdown
+ *   renderContent={ () => (
+ *     <DropdownContentWrapper paddingSize="medium">
+ *       My dropdown content
+ *     </DropdownContentWrapper>
+ * ) }
+ * />
+ * ```
+ */
+export const DropdownContentWrapper = contextConnect(
+	UnconnectedDropdownContentWrapper,
+	'DropdownContentWrapper'
+);
+
+export default DropdownContentWrapper;

package/src/dropdown/stories/index.js

@@ -1,81 +1,72 @@
-/**
- * WordPress dependencies
- */
-import {
-	more,
-	arrowLeft,
-	arrowRight,
-	arrowUp,
-	arrowDown,
-} from '@wordpress/icons';
-
 /**
  * Internal dependencies
  */
 import Dropdown from '../';
 import Button from '../../button';
-import MenuGroup from '../../menu-group';
-import MenuItem from '../../menu-item';
-import DropdownMenu from '../../dropdown-menu';
+import { DropdownContentWrapper } from '../dropdown-content-wrapper';
 
-export default { title: 'Components/Dropdown', component: Dropdown };
+export default {
+	title: 'Components/Dropdown',
+	component: Dropdown,
+	subcomponents: { DropdownContentWrapper },
+	argTypes: {
+		expandOnMobile: { control: { type: 'boolean' } },
+		focusOnMount: {
+			control: {
+				type: 'radio',
+				options: [ 'firstElement', 'container', false ],
+			},
+		},
+		headerTitle: { control: { type: 'text' } },
+		renderContent: { control: { type: null } },
+		renderToggle: { control: { type: null } },
+	},
+};
 
-const DropdownAndDropdownMenuExample = () => {
+const Template = ( args ) => {
 	return (
-		<>
-			<div>
-				<p>This is a DropdownMenu component:</p>
-				<DropdownMenu
-					icon={ more }
-					label="Select a direction"
-					controls={ [
-						{
-							title: 'Up',
-							icon: arrowUp,
-						},
-						{
-							title: 'Right',
-							icon: arrowRight,
-						},
-						{
-							title: 'Down',
-							icon: arrowDown,
-						},
-						{
-							title: 'Left',
-							icon: arrowLeft,
-						},
-					] }
-				/>
-			</div>
-			<div>
-				<p>This is an assembled Dropdown component:</p>
-				<Dropdown
-					className="my-container-class-name"
-					contentClassName="my-popover-content-classname"
-					position="bottom right"
-					renderToggle={ ( { isOpen, onToggle } ) => (
-						<Button
-							icon={ more }
-							onClick={ onToggle }
-							aria-expanded={ isOpen }
-							label="Select a direction"
-						/>
-					) }
-					renderContent={ () => (
-						<MenuGroup>
-							<MenuItem icon={ arrowUp }>Up</MenuItem>
-							<MenuItem icon={ arrowDown }>Down</MenuItem>
-							<MenuItem icon={ arrowLeft }>Left</MenuItem>
-							<MenuItem icon={ arrowRight }>Right</MenuItem>
-						</MenuGroup>
-					) }
-				/>
-			</div>
-		</>
+		<div style={ { height: 150 } }>
+			<Dropdown { ...args } />
+		</div>
 	);
 };
 
-export const _default = () => {
-	return <DropdownAndDropdownMenuExample />;
+export const Default = Template.bind( {} );
+Default.args = {
+	position: 'bottom right',
+	renderToggle: ( { isOpen, onToggle } ) => (
+		<Button onClick={ onToggle } aria-expanded={ isOpen } isPrimary>
+			Open dropdown
+		</Button>
+	),
+	renderContent: () => <div>This is the dropdown content.</div>,
+};
+
+/**
+ * To apply more padding to the dropdown content, use the provided `<DropdownContentWrapper>`
+ * convenience wrapper. A `paddingSize` of `"medium"` is suitable for relatively larger dropdowns (default is `"small"`).
+ */
+export const WithMorePadding = Template.bind( {} );
+WithMorePadding.args = {
+	...Default.args,
+	renderContent: () => (
+		<DropdownContentWrapper paddingSize="medium">
+			Content wrapped with <code>{ `paddingSize="medium"` }</code>.
+		</DropdownContentWrapper>
+	),
+};
+
+/**
+ * The `<DropdownContentWrapper>` convenience wrapper can also be used to remove padding entirely,
+ * with a `paddingSize` of `"none"`. This can also serve as a clean foundation to add arbitrary
+ * paddings, for example when child components already have padding on their own.
+ */
+export const WithNoPadding = Template.bind( {} );
+WithNoPadding.args = {
+	...Default.args,
+	renderContent: () => (
+		<DropdownContentWrapper paddingSize="none">
+			Content wrapped with <code>{ `paddingSize="none"` }</code>.
+		</DropdownContentWrapper>
+	),
 };

package/src/dropdown/styles.ts

@@ -0,0 +1,38 @@
+/**
+ * External dependencies
+ */
+import { css } from '@emotion/react';
+import styled from '@emotion/styled';
+
+/**
+ * Internal dependencies
+ */
+import { space } from '../ui/utils/space';
+import type { DropdownContentWrapperProps } from './types';
+
+const padding = ( { paddingSize = 'small' }: DropdownContentWrapperProps ) => {
+	if ( paddingSize === 'none' ) return;
+
+	const paddingValues = {
+		small: space( 2 ),
+		medium: space( 4 ),
+	};
+
+	return css`
+		padding: ${ paddingValues[ paddingSize ] || paddingValues.small };
+	`;
+};
+
+export const DropdownContentWrapperDiv = styled.div< DropdownContentWrapperProps >`
+	// Negative margin to reset (offset) the default padding on .components-popover__content
+	margin-left: ${ space( -2 ) };
+	margin-right: ${ space( -2 ) };
+	&:first-of-type {
+		margin-top: ${ space( -2 ) };
+	}
+	&:last-of-type {
+		margin-bottom: ${ space( -2 ) };
+	}
+
+	${ padding };
+`;

package/src/dropdown/types.ts

@@ -0,0 +1,8 @@
+export type DropdownContentWrapperProps = {
+	/**
+	 * Amount of padding to apply on the dropdown content.
+	 *
+	 * @default 'small'
+	 */
+	paddingSize?: 'none' | 'small' | 'medium';
+};

package/src/elevation/README.md

@@ -33,46 +33,45 @@ function Example() {
 
 Size of the shadow value when active (see the `value` and `isInteractive` props).
 
-- Required: No
+-   Required: No
 
 ### `borderRadius`: `CSSProperties[ 'borderRadius' ]`
 
 Renders the border-radius of the shadow.
 
-- Required: No
-- Default: `inherit`
+-   Required: No
+-   Default: `inherit`
 
 ### `focus`: `number`
 
-Size of the shadow value when focused (see the `value` and `isInteractive` props).
+Size of the shadow value when focused (see the `value` and `isInteractive`props).
 
-- Required: No
+-   Required: No
 
 ### `hover`: `number`
 
-Size of the shadow value when hovered  (see the `value` and `isInteractive` props).
+Size of the shadow value when hovered (see the `value` and `isInteractive` props).
 
-- Required: No
+-   Required: No
 
 ### `isInteractive`: `boolean`
 
 Determines if `hover`, `active`, and `focus` shadow values should be automatically calculated and rendered.
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 ### `offset`: `number`
 
 Dimensional offsets (margin) for the shadow.
 
-- Required: No
-- Default: `0`
+-   Required: No
+-   Default: `0`
 
-### `value`
-
-**Type**: `number`
+### `value`: `number`
 
 Size of the shadow, based on the Style system's elevation system. The `value` determines the strength of the shadow, which sense of depth.
+
 In the example below, `isInteractive` is activated to give a better sense of depth.
 
 ```jsx
@@ -86,3 +85,6 @@ function Example() {
 	);
 }
 ```
+
+-   Required: No
+-   Default: `0`

package/src/elevation/component.tsx

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, WordPressComponentProps } from '../ui/context';
+import { View } from '../view';
+import { useElevation } from './hook';
+import type { ElevationProps } from './types';
+
+function UnconnectedElevation(
+	props: WordPressComponentProps< ElevationProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const elevationProps = useElevation( props );
+
+	return <View { ...elevationProps } ref={ forwardedRef } />;
+}
+
+/**
+ * `Elevation` is a core component that renders shadow, using the component
+ * system's shadow system.
+ *
+ * The shadow effect is generated using the `value` prop.
+ *
+ * ```jsx
+ * import {
+ *	__experimentalElevation as Elevation,
+ *	__experimentalSurface as Surface,
+ *	__experimentalText as Text,
+ * } from '@wordpress/components';
+ *
+ * function Example() {
+ *   return (
+ *     <Surface>
+ *       <Text>Code is Poetry</Text>
+ *       <Elevation value={ 5 } />
+ *     </Surface>
+ *   );
+ * }
+ * ```
+ */
+export const Elevation = contextConnect( UnconnectedElevation, 'Elevation' );
+
+export default Elevation;

package/src/elevation/{hook.js → hook.ts}

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { css } from '@emotion/react';
+import { css, SerializedStyles } from '@emotion/react';
 
 /**
  * WordPress dependencies
@@ -11,28 +11,24 @@ import { useMemo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import * as styles from './styles';
 import { CONFIG, reduceMotion } from '../utils';
 import { useCx } from '../utils/hooks/use-cx';
 import { isValueDefined } from '../utils/values';
+import type { ElevationProps } from './types';
 
-/**
- * @param {number} value
- * @return {string} The box shadow value.
- */
-export function getBoxShadow( value ) {
-	const boxShadowColor = `rgba(0 ,0, 0, ${ value / 20 })`;
+export function getBoxShadow( value: number ) {
+	const boxShadowColor = `rgba(0, 0, 0, ${ value / 20 })`;
 	const boxShadow = `0 ${ value }px ${ value * 2 }px 0
 	${ boxShadowColor }`;
 
 	return boxShadow;
 }
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-export function useElevation( props ) {
+export function useElevation(
+	props: WordPressComponentProps< ElevationProps, 'div' >
+) {
 	const {
 		active,
 		borderRadius = 'inherit',
@@ -48,10 +44,12 @@ export function useElevation( props ) {
 	const cx = useCx();
 
 	const classes = useMemo( () => {
-		/** @type {number | undefined} */
-		let hoverValue = isValueDefined( hover ) ? hover : value * 2;
-		/** @type {number | undefined} */
-		let activeValue = isValueDefined( active ) ? active : value / 2;
+		let hoverValue: number | undefined = isValueDefined( hover )
+			? hover
+			: value * 2;
+		let activeValue: number | undefined = isValueDefined( active )
+			? active
+			: value / 2;
 
 		if ( ! isInteractive ) {
 			hoverValue = isValueDefined( hover ) ? hover : undefined;
@@ -60,7 +58,12 @@ export function useElevation( props ) {
 
 		const transition = `box-shadow ${ CONFIG.transitionDuration } ${ CONFIG.transitionTimingFunction }`;
 
-		const sx = {};
+		const sx: {
+			Base?: SerializedStyles;
+			hover?: SerializedStyles;
+			active?: SerializedStyles;
+			focus?: SerializedStyles;
+		} = {};
 
 		sx.Base = css(
 			{

package/src/elevation/stories/index.tsx

@@ -0,0 +1,85 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { Elevation } from '..';
+
+const meta: ComponentMeta< typeof Elevation > = {
+	component: Elevation,
+	title: 'Components (Experimental)/Elevation',
+	argTypes: {
+		as: { control: { type: 'text' } },
+		borderRadius: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof Elevation > = ( args ) => {
+	return (
+		<div
+			style={ {
+				width: 150,
+				height: 150,
+				position: 'relative',
+			} }
+		>
+			<Elevation { ...args } />
+		</div>
+	);
+};
+
+const InteractiveTemplate: ComponentStory< typeof Elevation > = ( args ) => {
+	return (
+		<button
+			style={ {
+				border: 0,
+				background: 'transparent',
+				width: 150,
+				height: 150,
+				position: 'relative',
+			} }
+		>
+			Click me
+			<Elevation { ...args } />
+		</button>
+	);
+};
+
+export const Default: ComponentStory< typeof Elevation > = Template.bind( {} );
+Default.args = {
+	value: 5,
+};
+
+/**
+ * Enable the `isInteractive` prop to automatically generate values
+ * for the hover/active/focus states.
+ */
+export const WithInteractive: ComponentStory< typeof Elevation > =
+	InteractiveTemplate.bind( {} );
+WithInteractive.args = {
+	...Default.args,
+	isInteractive: true,
+};
+
+/**
+ * You can also provide custom values for the hover/active/focus states
+ * instead of using the `isInteractive` prop.
+ */
+export const WithCustomInteractive: ComponentStory< typeof Elevation > =
+	InteractiveTemplate.bind( {} );
+WithCustomInteractive.args = {
+	...Default.args,
+	hover: 7,
+	active: 1,
+	focus: 10,
+};