diff --git a/packages/components/src/box-control/README.md b/packages/components/src/box-control/README.md index 77176b49eeb6d..ddadf938798ee 100644 --- a/packages/components/src/box-control/README.md +++ b/packages/components/src/box-control/README.md @@ -1,106 +1,125 @@ # BoxControl -A control that lets users set values for top, right, bottom, and left. Can be used as an input control for values like `padding` or `margin`. + -## Usage +

See the WordPress Storybook for more detailed, interactive documentation.

+ +A control that lets users set values for top, right, bottom, and left. Can be +used as an input control for values like `padding` or `margin`. ```jsx import { useState } from 'react'; import { BoxControl } from '@wordpress/components'; function Example() { - const [ values, setValues ] = useState( { - top: '50px', - left: '10%', - right: '10%', - bottom: '50px', - } ); - - return ( - setValues( nextValues ) } - /> - ); -} + const [ values, setValues ] = useState( { + top: '50px', + left: '10%', + right: '10%', + bottom: '50px', + } ); + + return ( + + ); +}; ``` - ## Props -### `allowReset`: `boolean` +### `__next40pxDefaultSize` + +Start opting into the larger default height that will become the default size in a future version. + + - Type: `boolean` + - Required: No + - Default: `false` + +### `allowReset` If this property is true, a button to reset the box control is rendered. -- Required: No -- Default: `true` + - Type: `boolean` + - Required: No + - Default: `true` -### `splitOnAxis`: `boolean` +### `id` -If this property is true, when the box control is unlinked, vertical and horizontal controls can be used instead of updating individual sides. +The id to use as a base for the unique HTML id attribute of the control. -- Required: No -- Default: `false` + - Type: `string` + - Required: No -### `inputProps`: `object` +### `inputProps` -Props for the internal [UnitControl](../unit-control) components. +Props for the internal `UnitControl` components. -- Required: No -- Default: `{ min: 0 }` + - Type: `UnitControlPassthroughProps` + - Required: No + - Default: `{ + min: 0, + }` -### `label`: `string` +### `label` Heading label for the control. -- Required: No -- Default: `__( 'Box Control' )` + - Type: `string` + - Required: No + - Default: `__( 'Box Control' )` -### `onChange`: `(next: BoxControlValue) => void` +### `onChange` A callback function when an input value changes. -- Required: Yes + - Type: `(next: BoxControlValue) => void` + - Required: No + - Default: `() => {}` -### `resetValues`: `object` +### `resetValues` The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset. -- Required: No -- Default: `{ top: undefined, right: undefined, bottom: undefined, left: undefined }` - -### `sides`: `string[]` - -Collection of sides to allow control of. If omitted or empty, all sides will be available. Allowed values are "top", "right", "bottom", "left", "vertical", and "horizontal". - -- Required: No - -### `units`: `WPUnitControlUnit[]` - -Collection of available units which are compatible with [UnitControl](../unit-control). + - Type: `BoxControlValue` + - Required: No + - Default: `{ + top: undefined, + right: undefined, + bottom: undefined, + left: undefined, + }` -- Required: No +### `sides` -### `values`: `object` +Collection of sides to allow control of. If omitted or empty, all sides will be available. -The `top`, `right`, `bottom`, and `left` box dimension values. +Allowed values are "top", "right", "bottom", "left", "vertical", and "horizontal". -- Required: No + - Type: `readonly (keyof BoxControlValue | "horizontal" | "vertical")[]` + - Required: No -### `onMouseOver`: `function` +### `splitOnAxis` -A handler for onMouseOver events. +If this property is true, when the box control is unlinked, vertical and horizontal controls +can be used instead of updating individual sides. -- Required: No + - Type: `boolean` + - Required: No + - Default: `false` -### `onMouseOut`: `function` +### `units` -A handler for onMouseOut events. +Available units to select from. -- Required: No + - Type: `WPUnitControlUnit[]` + - Required: No + - Default: `CSS_UNITS` -### `__next40pxDefaultSize`: `boolean` +### `values` -Start opting into the larger default size that will become the default size in a future version. +The current values of the control, expressed as an object of `top`, `right`, `bottom`, and `left` values. -- Required: No -- Default: `false` + - Type: `BoxControlValue` + - Required: No diff --git a/packages/components/src/box-control/docs-manifest.json b/packages/components/src/box-control/docs-manifest.json new file mode 100644 index 0000000000000..c506e7a9e27ee --- /dev/null +++ b/packages/components/src/box-control/docs-manifest.json @@ -0,0 +1,5 @@ +{ + "$schema": "../../schemas/docs-manifest.json", + "displayName": "BoxControl", + "filePath": "./index.tsx" +} diff --git a/packages/components/src/box-control/index.tsx b/packages/components/src/box-control/index.tsx index 41e95aa88bea3..7f822f5f70e12 100644 --- a/packages/components/src/box-control/index.tsx +++ b/packages/components/src/box-control/index.tsx @@ -51,23 +51,23 @@ function useUniqueId( idProp?: string ) { * used as an input control for values like `padding` or `margin`. * * ```jsx + * import { useState } from 'react'; * import { BoxControl } from '@wordpress/components'; - * import { useState } from '@wordpress/element'; * * function Example() { - * const [ values, setValues ] = useState( { - * top: '50px', - * left: '10%', - * right: '10%', - * bottom: '50px', - * } ); + * const [ values, setValues ] = useState( { + * top: '50px', + * left: '10%', + * right: '10%', + * bottom: '50px', + * } ); * - * return ( - * setValues( nextValues ) } - * /> - * ); + * return ( + * + * ); * }; * ``` */ diff --git a/packages/components/src/box-control/types.ts b/packages/components/src/box-control/types.ts index 5f4071aeed88a..2a47abbf11001 100644 --- a/packages/components/src/box-control/types.ts +++ b/packages/components/src/box-control/types.ts @@ -58,6 +58,8 @@ export type BoxControlProps = Pick< resetValues?: BoxControlValue; /** * Collection of sides to allow control of. If omitted or empty, all sides will be available. + * + * Allowed values are "top", "right", "bottom", "left", "vertical", and "horizontal". */ sides?: readonly ( keyof BoxControlValue | 'horizontal' | 'vertical' )[]; /**