Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ToolsPanel: Add a readme section related to laying out a ToolsPanel #42615

Merged
merged 2 commits into from
Jul 22, 2022
Merged

ToolsPanel: Add a readme section related to laying out a ToolsPanel #42615

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d59728d
Add a readme section related to laying out a ToolsPanel
aaronrobertshaw Jul 22, 2022
e726b47
Add changelog
aaronrobertshaw Jul 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/components/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
- `CustomSelectControl`: Add flag to opt in to unconstrained width ([#42460](https://github.com/WordPress/gutenberg/pull/42460/)).
- `BorderControl`: Render dropdown as prefix within its `UnitControl` ([#42212](https://github.com/WordPress/gutenberg/pull/42212/))
- `UnitControl`: Update prop types to allow ReactNode as prefix ([#42212](https://github.com/WordPress/gutenberg/pull/42212/))
- `ToolsPanel`: Updated README with panel layout information and more expansive usage example ([#42615](https://github.com/WordPress/gutenberg/pull/42615)).

### Internal

Expand Down
115 changes: 94 additions & 21 deletions packages/components/src/tools-panel/tools-panel/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
);
}
Expand Down