-
Notifications
You must be signed in to change notification settings - Fork 4.2k
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.
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
Components: promote ItemGroup
#33701
Merged
Merged
Changes from all commits
Commits
Show all changes
17 commits
Select commit
Hold shift + click to select a range
60cdea0
Move `item-group` folder from `src/ui` to `src/`, update import paths
ciampo 7159e7e
Export from @wordpress/components as experimental components
ciampo d19c4b5
Import `COLORS` and `CONFIG` from same path
ciampo ab49c6a
Refactor folder structure
ciampo 836bd9c
Add draft READMEs
ciampo 9ed8758
Add JSDocs to types
ciampo e680873
Update README with prop descriptions
ciampo 9a280ff
Storybook: Allow undefined size for Item, change initial props values…
ciampo 4c77238
Add context section and components description to README
ciampo f58ee76
Add `children` to the types
ciampo 42e38ff
Wrap every item in a `div` component to make sure that all children o…
ciampo 7b575a7
Add unit tests
ciampo a814b9d
Merge together imports from same path
ciampo 1374e2a
Use wrapper.container.firstChild in snapshot unit tests
ciampo 4c23f28
Make `isBordered` only control the borders around the item-group (and…
ciampo bd4bc7e
Adjust styles to keep into account the extra `div` wrapper around eac…
ciampo 7ce7cd3
Update snapshots
ciampo File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
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
File renamed without changes.
File renamed without changes.
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,78 @@ | ||
# `ItemGroup` | ||
|
||
<div class="callout callout-alert"> | ||
This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. | ||
</div> | ||
|
||
`ItemGroup` displays a list of `Item`s grouped and styled together. | ||
|
||
## Usage | ||
|
||
`ItemGroup` should be used in combination with the [`Item` sub-component](/packages/components/src/item-group/item/README.md). | ||
|
||
```jsx | ||
import { | ||
__experimentalItemGroup as ItemGroup, | ||
__experimentalItem as Item, | ||
} from '@wordpress/components'; | ||
|
||
function Example() { | ||
return ( | ||
<ItemGroup> | ||
<Item>Code</Item> | ||
<Item>is</Item> | ||
<Item>Poetry</Item> | ||
</ItemGroup> | ||
); | ||
} | ||
``` | ||
|
||
## Props | ||
|
||
### `isBordered`: `boolean` | ||
|
||
Renders borders around each items. | ||
|
||
- Required: No | ||
- Default: `false` | ||
|
||
### `isRounded`: `boolean` | ||
|
||
Renders with rounded corners. | ||
|
||
- Required: No | ||
- Default: `true` | ||
|
||
### `isSeparated`: `boolean` | ||
|
||
Renders items individually. Even if `isBordered` is `false`, a border in between each item will be still be displayed. | ||
|
||
- Required: No | ||
- Default: `false` | ||
|
||
### `size`: `'small' | 'medium' | 'large'` | ||
|
||
Determines the amount of padding within the component. | ||
When not defined, it defaults to the value from the context (which is `medium` by default). | ||
|
||
- Required: No | ||
- Default: `medium` | ||
|
||
### Context | ||
|
||
The [`Item` sub-component](/packages/components/src/item-group/item/README.md) is connected to `<ItemGroup />` using [Context](https://reactjs.org/docs/context.html). Therefore, `Item` receives the `size` prop from the `ItemGroup` parent component. | ||
|
||
In the following example, the `<Item />` will render with a size of `small`: | ||
|
||
```jsx | ||
import { | ||
__experimentalItemGroup as ItemGroup, | ||
__experimentalItem as Item, | ||
} from '@wordpress/components'; | ||
|
||
const Example = () => ( | ||
<ItemGroup size="small"> | ||
<Item>Item text</Item> | ||
</ItemGroup> | ||
); | ||
``` |
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
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,2 @@ | ||
export { default } from './component'; | ||
export { useItemGroup } from './hook'; |
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,63 @@ | ||
# `Item` | ||
|
||
<div class="callout callout-alert"> | ||
This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. | ||
</div> | ||
|
||
`Item` is used in combination with `ItemGroup` to display a list of items grouped and styled together. | ||
|
||
## Usage | ||
|
||
`Item` should be used in combination with the [`ItemGroup` component](/packages/components/src/item-group/item-group/README.md). | ||
|
||
```jsx | ||
import { | ||
__experimentalItemGroup as ItemGroup, | ||
__experimentalItem as Item, | ||
} from '@wordpress/components'; | ||
|
||
function Example() { | ||
return ( | ||
<ItemGroup> | ||
<Item>Code</Item> | ||
<Item>is</Item> | ||
<Item>Poetry</Item> | ||
</ItemGroup> | ||
); | ||
} | ||
``` | ||
|
||
## Props | ||
|
||
### `isAction`: `boolean` | ||
|
||
Renders the item as an interactive `button` element. | ||
|
||
- Required: No | ||
- Default: `false` | ||
|
||
### `size`: `'small' | 'medium' | 'large'` | ||
|
||
Determines the amount of padding within the component. | ||
|
||
- Required: No | ||
- Default: `medium` | ||
|
||
### Context | ||
|
||
`Item` is connected to [the `<ItemGroup />` parent component](/packages/components/src/item-group/item-group/README.md) using [Context](https://reactjs.org/docs/context.html). Therefore, `Item` receives the `size` prop from the `ItemGroup` parent component. | ||
|
||
In the following example, the `<Item />` will render with a size of `small`: | ||
|
||
```jsx | ||
import { | ||
__experimentalItemGroup as ItemGroup, | ||
__experimentalItem as Item, | ||
} from '@wordpress/components'; | ||
|
||
const Example = () => ( | ||
<ItemGroup size="small"> | ||
<Item>...</Item> | ||
</ItemGroup> | ||
); | ||
``` |
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,28 @@ | ||
/** | ||
* External dependencies | ||
*/ | ||
// eslint-disable-next-line no-restricted-imports | ||
import type { Ref } from 'react'; | ||
|
||
/** | ||
* Internal dependencies | ||
*/ | ||
import type { ItemProps } from '../types'; | ||
import { useItem } from './hook'; | ||
import { contextConnect, PolymorphicComponentProps } from '../../ui/context'; | ||
import { View } from '../../view'; | ||
|
||
function Item( | ||
props: PolymorphicComponentProps< ItemProps, 'div' >, | ||
forwardedRef: Ref< any > | ||
) { | ||
const { role, wrapperClassName, ...otherProps } = useItem( props ); | ||
|
||
return ( | ||
<div role={ role } className={ wrapperClassName }> | ||
<View { ...otherProps } ref={ forwardedRef } /> | ||
</div> | ||
); | ||
} | ||
|
||
export default contextConnect( Item, 'Item' ); |
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
export { default } from './component'; | ||
export { useItem } from './hook'; |
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.
I wonder if this should be
"parent": "item-group"
. But I'm not sure if this level of nesting actually works or is desirable in the Handbook. @gziolo Any thoughts?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 structure in the handbook is rather flat for components. So I would leave it as is.
The other question is whether
<Item />
really depends on the<ItemGroup />
. In other cases grouping is optional.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.
Item
is quite dependant onItemGroup
at the moment — for example, it reads theItemGroup
context in order to derive values for thesize
prop.On its own, it's not very feature-full, nor opinionated in terms of styling. It really just is a
div[role="listitem"]
which renders adiv
or abutton
depending on theisAction
prop.