BoxControl: Auto-generate readme #67284
+99
−73
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,106 +1,125 @@ | ||
| # BoxControl | ||
|
|
||
| <!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. --> | ||
|
|
||
| <p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-boxcontrol--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p> | ||
|
|
||
| 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 ( | ||
| <BoxControl | ||
| values={ values } | ||
| onChange={ setValues } | ||
| /> | ||
| ); | ||
| }; | ||
| ``` | ||
| ## Props | ||
|
|
||
| ### `__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. | ||
|
|
||
| - Type: `boolean` | ||
| - Required: No | ||
| - Default: `true` | ||
|
|
||
| ### `id` | ||
|
|
||
| The id to use as a base for the unique HTML id attribute of the control. | ||
|
|
||
| - Type: `string` | ||
| - Required: No | ||
|
|
||
| ### `inputProps` | ||
|
|
||
| Props for the internal `UnitControl` components. | ||
|
|
||
| - Type: `UnitControlPassthroughProps` | ||
| - Required: No | ||
| - Default: `{ | ||
| min: 0, | ||
| }` | ||
|
|
||
| ### `label` | ||
|
|
||
| Heading label for the control. | ||
|
|
||
| - Type: `string` | ||
| - Required: No | ||
| - Default: `__( 'Box Control' )` | ||
|
|
||
| ### `onChange` | ||
|
|
||
| A callback function when an input value changes. | ||
|
|
||
| - Type: `(next: BoxControlValue) => void` | ||
| - Required: No | ||
| - Default: `() => {}` | ||
|
|
||
| ### `resetValues` | ||
|
|
||
| The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset. | ||
|
|
||
| - Type: `BoxControlValue` | ||
| - Required: No | ||
| - Default: `{ | ||
| top: undefined, | ||
| right: undefined, | ||
| bottom: undefined, | ||
| left: undefined, | ||
| }` | ||
|
|
||
| ### `sides` | ||
|
|
||
| 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". | ||
|
|
||
| - Type: `readonly (keyof BoxControlValue | "horizontal" | "vertical")[]` | ||
| - Required: No | ||
|
|
||
| ### `splitOnAxis` | ||
|
|
||
| If this property is true, when the box control is unlinked, vertical and horizontal controls | ||
| can be used instead of updating individual sides. | ||
|
|
||
| - Type: `boolean` | ||
| - Required: No | ||
| - Default: `false` | ||
|
|
||
| ### `units` | ||
|
|
||
| Available units to select from. | ||
|
|
||
| - Type: `WPUnitControlUnit[]` | ||
| - Required: No | ||
| - Default: `CSS_UNITS` | ||
|
|
||
| ### `values` | ||
|
|
||
| The current values of the control, expressed as an object of `top`, `right`, `bottom`, and `left` values. | ||
|
|
||
| - Type: `BoxControlValue` | ||
| - Required: No | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| { | ||
| "$schema": "../../schemas/docs-manifest.json", | ||
| "displayName": "BoxControl", | ||
| "filePath": "./index.tsx" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What's the thing about those props like
onMouseOutandonMouseOverthat we previously documented in the README but we no longer do? Does that signal a gap in types perhaps?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The types are correct, it's just the default behavior of
react-docgen-typescriptto suppress element props that are optional and don't have explicit descriptions. I think that makes sense, especially becauseonMouseOutandonMouseOverare highly unlikely to be used in common BoxControl use cases, and their inclusion is simply arbitrary (probably only happened because some weird edge case in Gutenberg required it).What annoys me though is that there's quirk in the API where
onMouseOutandonMouseOvershould actually just be passed as part of theinputPropsprop. That's basically what happens under the hood anyway. I'll address this in a separate PR — it should just be a change in TypeScript metadata.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sounds good, thanks for clarifying 👍