Skip to content

Commit 368ce32

Browse files
tiffany-sy-linTiffany LinreidbarberdevongovettLFDanLu
authored
TagGroup documentation (#3629)
* new taggroup docs * remove comment * add remove functionality to docs * add prop descriptions, remove unused props * remove disabledKeys and isDisabled * update docs for removing * update remove function * add description * add events section * add section for icons * Update packages/@react-spectrum/tag/docs/TagGroup.mdx Co-authored-by: Daniel Lu <[email protected]> * update category * add aria props & verbage feedback Co-authored-by: Tiffany Lin <[email protected]> Co-authored-by: Reid Barber <[email protected]> Co-authored-by: Devon Govett <[email protected]> Co-authored-by: Daniel Lu <[email protected]>
1 parent 1503f63 commit 368ce32

File tree

2 files changed

+158
-2
lines changed

2 files changed

+158
-2
lines changed

‎packages/@react-spectrum/tag/docs/TagGroup.mdx

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
{/* Copyright 2022 Adobe. All rights reserved.
2+
This file is licensed to you under the Apache License, Version 2.0 (the "License");
3+
you may not use this file except in compliance with the License. You may obtain a copy
4+
of the License at http://www.apache.org/licenses/LICENSE-2.0
5+
Unless required by applicable law or agreed to in writing, software distributed under
6+
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
7+
OF ANY KIND, either express or implied. See the License for the specific language
8+
governing permissions and limitations under the License. */}
9+
10+
import {Layout} from '@react-spectrum/docs';
11+
export default Layout;
12+
13+
import docs from 'docs:@react-spectrum/tag';
14+
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
15+
import packageData from '@react-spectrum/tag/package.json';
16+
17+
```jsx import
18+
import {Flex} from '@react-spectrum/layout';
19+
import {Item, TagGroup} from '@react-spectrum/tag';
20+
import News from '@spectrum-icons/workflow/News';
21+
import Airplane from '@spectrum-icons/workflow/Airplane';
22+
import Game from '@spectrum-icons/workflow/Game';
23+
import ShoppingCart from '@spectrum-icons/workflow/ShoppingCart';
24+
import {Text} from '@react-spectrum/text';
25+
```
26+
27+
---
28+
category: Status
29+
keywords: [TagGroup, status]
30+
---
31+
32+
# TagGroup
33+
34+
<PageDescription>{docs.exports.TagGroup.description}</PageDescription>
35+
36+
<HeaderInfo
37+
packageData={packageData}
38+
componentNames={['Item', 'TagGroup']}
39+
sourceData={[
40+
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/tag/'}
41+
]} />
42+
43+
## Example
44+
```tsx example
45+
<TagGroup aria-label="Static TagGroup items example">
46+
<Item>Adobe Photoshop</Item>
47+
<Item>Adobe InDesign</Item>
48+
<Item>Adobe AfterEffects</Item>
49+
<Item>Adobe Illustrator</Item>
50+
<Item>Adobe Lightroom</Item>
51+
</TagGroup>
52+
```
53+
54+
## Content
55+
TagGroup is a component that allows users to categorize content. Basic usage of TagGroup, seen in the example above, shows the use of a static collection where the contents of the TagGroup are hard coded.
56+
Dynamic collections, as shown below, can be used when the options come from an external data source such as an API, or update over time.
57+
58+
Each item has a unique key defined by the data. In the example below, the `key` of each row element is implicitly defined by the id property of the row object.
59+
See [collections](../react-stately/collections.html#unique-keys) to learn more about keys in dynamic collections.
60+
61+
```tsx example
62+
const items = [
63+
{id: 1, name: 'Adobe Photoshop'},
64+
{id: 2, name: 'Adobe XD'},
65+
{id: 3, name: 'Adobe InDesign'},
66+
{id: 4, name: 'Adobe AfterEffects'},
67+
{id: 5, name: 'Adobe Illustrator'},
68+
{id: 6, name: 'Adobe Lightroom'},
69+
{id: 7, name: 'Adobe Premiere Pro'},
70+
{id: 8, name: 'Adobe Fresco'},
71+
{id: 9, name: 'Adobe Dreamweaver'}
72+
];
73+
74+
<Flex width={500}>
75+
<TagGroup items={items} aria-label="Dynamic TagGroup items example">
76+
{item => <Item>{item.name}</Item>}
77+
</TagGroup>
78+
</Flex>
79+
```
80+
81+
### Internationalization
82+
To internationalize a TagGroup, all text content within the TagGroup should be localized. This includes the `aria-label` provided to the TagGroup if any.
83+
For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of TagGroup is automatically flipped.
84+
85+
## Labeling
86+
### Accessibility
87+
An `aria-label` must be provided to the TagGroup for accessibility. If the TagGroup is labeled by a separate element, an `aria-labelledby` prop must be provided using the id of the labeling element instead.
88+
89+
## Events
90+
91+
Removing tags can be enabled by providing the `allowsRemoving` prop to the TagGroup. TagGroup will pass the key of the removed item to the `onRemove` handler as shown below.
92+
93+
```tsx example
94+
function Example() {
95+
let defaultItems = [
96+
{id: 1, name: 'Adobe Photoshop'},
97+
{id: 2, name: 'Adobe XD'},
98+
{id: 3, name: 'Adobe InDesign'},
99+
{id: 4, name: 'Adobe AfterEffects'},
100+
{id: 5, name: 'Adobe Illustrator'},
101+
{id: 6, name: 'Adobe Lightroom'},
102+
{id: 7, name: 'Adobe Premiere Pro'},
103+
{id: 8, name: 'Adobe Fresco'},
104+
{id: 9, name: 'Adobe Dreamweaver'}
105+
];
106+
107+
let [items, setItems] = React.useState(defaultItems);
108+
109+
let removeItem = (key) => {
110+
setItems(prevItems => prevItems.filter((item) => key !== item.id));
111+
};
112+
113+
return (
114+
<Flex width={500}>
115+
<TagGroup items={items} allowsRemoving onRemove={removeItem} aria-label="Removable TagGroup example">
116+
{item => <Item>{item.name}</Item>}
117+
</TagGroup>
118+
</Flex>
119+
);
120+
}
121+
```
122+
123+
## Props
124+
125+
<PropTable component={{
126+
...docs.exports.TagGroup,
127+
props: {
128+
...docs.exports.TagGroup.props,
129+
properties: Object.fromEntries(Object.entries(docs.exports.TagGroup.props.properties))
130+
}
131+
}} links={docs.links} />
132+
133+
## Visual options
134+
135+
### With icons
136+
137+
```tsx example
138+
<TagGroup aria-label="TagGroup with icons example">
139+
<Item>
140+
<News />
141+
<Text>News</Text>
142+
</Item>
143+
<Item>
144+
<Airplane />
145+
<Text>Travel</Text>
146+
</Item>
147+
<Item>
148+
<Game />
149+
<Text>Gaming</Text>
150+
</Item>
151+
<Item>
152+
<ShoppingCart />
153+
<Text>Shopping</Text>
154+
</Item>
155+
</TagGroup>
156+
```

‎packages/@react-types/tag/src/index.d.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
* governing permissions and limitations under the License.
1111
*/
1212

13-
import {CollectionBase, DOMProps, ItemProps, Node, StyleProps} from '@react-types/shared';
13+
import {AriaLabelingProps, CollectionBase, DOMProps, ItemProps, Node, StyleProps} from '@react-types/shared';
1414
import {GridState} from '@react-stately/grid';
1515
import {Key, RefObject} from 'react';
1616

@@ -21,7 +21,7 @@ export interface TagGroupProps<T> extends Omit<CollectionBase<T>, 'disabledKeys'
2121
onRemove?: (key: Key) => void
2222
}
2323

24-
export interface SpectrumTagGroupProps<T> extends TagGroupProps<T>, DOMProps, StyleProps {}
24+
export interface SpectrumTagGroupProps<T> extends TagGroupProps<T>, DOMProps, StyleProps, AriaLabelingProps {}
2525

2626
export interface TagProps<T> extends ItemProps<any> {
2727
isFocused: boolean,

0 commit comments

Comments
 (0)