Skip to content

Commit 87dc68c

Browse files
marcosmouramarcosmoura
authored
docs: add migration guide for cards from V0 to V9 (#26186)
1 parent 581019d commit 87dc68c

7 files changed

Lines changed: 398 additions & 323 deletions

File tree

‎apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.Card.stories.mdx‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
import { Meta } from '@storybook/addon-docs';
2+
3+
<Meta title="Concepts/Migration/from v0/Components/Card Migration/Card" />
4+
5+
# Card Migration
6+
7+
## Overview
8+
9+
Before:
10+
11+
```tsx
12+
import { Card } from '@fluentui/react-northstar';
13+
const Component = () => <Card>Lorem ipsum, dolor sit amet consectetur adipisicing elit.</Card>;
14+
```
15+
16+
After:
17+
18+
```tsx
19+
import { Card } from '@fluentui/react-components/unstable';
20+
const Component = () => <Card>Lorem ipsum, dolor sit amet consectetur adipisicing elit.</Card>;
21+
```
22+
23+
## How to migrate props:
24+
25+
| Card props | migration guide |
26+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
27+
| as, className | keep it as is |
28+
| variables, styles | see Migrate style overrides in this document |
29+
| accessibility | see [migrate-custom-accessibility.md](?path=/docs/concepts-migrating-from-v0-custom-accessibility--page). Also check the focusMode new prop |
30+
| centered | REMOVED: see Migrate centered prop in this document |
31+
| compact | use `size="small"` |
32+
| disabled | REMOVED: No equivalent functionality. Can be created by overriding the styles. |
33+
| elevated | REMOVED: All cards are now elevated by default. To change that, use the `appearance` property. |
34+
| expandable | REMOVED: No equivalent functionality. |
35+
| fluid | REMOVED: see Migrate fluid prop in this document |
36+
| ghost | use `appearance="subtle"` |
37+
| inverted | use `appearance="filled-alternative"` |
38+
| size | keep it as is. Values: `small`, `medium`(default) and `large` |
39+
40+
## Migrate style overrides
41+
42+
⚠️ **If this is your first migration**, please read [the general guide on how to migrate styles](?path=/docs/concepts-migrating-from-v0-custom-style-overrides--page).
43+
44+
### Example for migrate boolean `variables`:
45+
46+
Before:
47+
48+
```tsx
49+
// in COMPONENT_NAME.tsx
50+
import { Card } from '@fluentui/react-northstar';
51+
52+
export const Component = () => <Card variables={{ isActionCard: true }} />;
53+
54+
// in Card-styles.ts
55+
export const CardStyles1 = {
56+
root: ({ variables: { isActionCard } }) => ({
57+
...(isActionCard && {
58+
color: colors.grey['250'],
59+
}),
60+
}),
61+
};
62+
```
63+
64+
After:
65+
66+
```tsx
67+
// in COMPONENT_NAME.tsx
68+
import { Card } from '@fluentui/react-components/unstable';
69+
import { useStyles } from './COMPONENT_NAME.styles.ts';
70+
71+
export const Component = () => {
72+
const classes = useStyles();
73+
74+
return <Card className={classes.actionCard}></Card>;
75+
};
76+
77+
// in COMPONENT_NAME.styles.ts
78+
import { makeStyles, tokens } from '@fluentui/react-components/unstable';
79+
80+
export const useStyles = makeStyles({
81+
actionCard: {
82+
color: colors.colorNeutralForeground1,
83+
},
84+
});
85+
```
86+
87+
### Example for migrate namespaced styles, with conditional styles via `variableProps`:
88+
89+
Before:
90+
91+
```tsx
92+
// in COMPONENT_NAME.tsx
93+
import { Card, useUIProviderContext } from '@fluentui/react-northstar';
94+
95+
export const Component = props => {
96+
const { vars } = useUIProviderContext();
97+
const { enableUsingChatListGroupTitleAsHeader } = props;
98+
return (
99+
<Card
100+
variables={vars('flyout', [
101+
{
102+
name: 'filterCard',
103+
props: {
104+
enableUsingChatListGroupTitleAsHeader,
105+
},
106+
},
107+
])}
108+
/>
109+
);
110+
};
111+
112+
// in Card-namespace-flyout.ts
113+
export default {
114+
root: {
115+
filterCard: ({ variableProps: { enableUsingChatListGroupTitleAsHeader } }) => ({
116+
...(enableUsingChatListGroupTitleAsHeader && {
117+
height: '3rem',
118+
width: '8rem',
119+
minWidth: '8rem',
120+
}),
121+
}),
122+
},
123+
};
124+
```
125+
126+
After:
127+
128+
```tsx
129+
// in COMPONENT_NAME.tsx
130+
import { Card, mergeClasses } from '@fluentui/react-components/unstable';
131+
import { useStyles } from './COMPONENT_NAME.styles.ts';
132+
133+
export const Component = props => {
134+
const classes = useStyles();
135+
136+
return (
137+
<Card
138+
className={mergeClasses(props.enableUsingChatListGroupTitleAsHeader && classes.chatListGroupTitleAsHeader)}
139+
></Card>
140+
);
141+
};
142+
143+
// in COMPONENT_NAME.styles.ts
144+
import { makeStyles } from '@fluentui/react-components/unstable';
145+
146+
export const useStyles = makeStyles({
147+
chatListGroupTitleAsHeader: {
148+
height: '3rem',
149+
width: '8rem',
150+
minWidth: '8rem',
151+
},
152+
});
153+
```
154+
155+
## Migrate `centered` prop
156+
157+
Can be achieved by overriding the styles of the Card component.
158+
159+
Before:
160+
161+
```tsx
162+
import { Card } from '@fluentui/react-northstar';
163+
164+
const Component = () => <Card centered>Lorem ipsum, dolor sit amet consectetur adipisicing elit.</Card>;
165+
```
166+
167+
After:
168+
169+
```tsx
170+
import * as React from 'react';
171+
import { makeStyles } from '@fluentui/react-components/unstable';
172+
import { Card } from '@fluentui/react-components/unstable';
173+
174+
const useStyles = makeStyles({
175+
centeredCard: {
176+
justifyItems: 'center',
177+
},
178+
});
179+
180+
export const CenteredCard = () => {
181+
const styles = useStyles();
182+
183+
return (
184+
<Card className={styles.centeredCard}>
185+
<p>Lorem ipsum dolor sit amet.</p>
186+
</Card>
187+
);
188+
};
189+
```
190+
191+
## Migrate `size` prop
192+
193+
All cards are fluid by default. To change that, use a parent container with a defined size.
194+
195+
Before:
196+
197+
```tsx
198+
import { Card } from '@fluentui/react-northstar';
199+
200+
const Component = () => <Card size="large">Lorem ipsum, dolor sit amet consectetur adipisicing elit.</Card>;
201+
```
202+
203+
After:
204+
205+
```jsx
206+
import * as React from 'react';
207+
import { makeStyles } from '@fluentui/react-components/unstable';
208+
import { Card } from '@fluentui/react-components/unstable';
209+
210+
const useStyles = makeStyles({
211+
parent: {
212+
width: '500px',
213+
},
214+
});
215+
216+
export const SizedCard = () => {
217+
const styles = useStyles();
218+
219+
return (
220+
<div className={styles.parent}>
221+
<Card>
222+
<p>Lorem ipsum dolor sit amet.</p>
223+
</Card>
224+
</div>
225+
);
226+
};
227+
```

‎apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardBody.stories.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
import { Meta } from '@storybook/addon-docs';
2+
3+
<Meta title="Concepts/Migration/from v0/Components/Card Migration/CardBody" />
4+
5+
# Card Body Migration
6+
7+
## Overview
8+
9+
This component is not needed anymore. Instead, pass any content under the main Card component.
10+
11+
Before:
12+
13+
```jsx
14+
import { Card, CardBody } from '@fluentui/react-northstar';
15+
16+
export const CardBodyExample = () => (
17+
<Card elevated>
18+
<CardBody fitted>
19+
<p>Lorem ipsum dolor sit amet.</p>
20+
</CardBody>
21+
</Card>
22+
);
23+
```
24+
25+
After:
26+
27+
```jsx
28+
import { Card } from '@fluentui/react-components/unstable';
29+
30+
export const CardBodyExample = () => (
31+
<Card>
32+
<p>Lorem ipsum dolor sit amet.</p>
33+
</Card>
34+
);
35+
```

‎apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardFooter.stories.mdx‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
import { Meta } from '@storybook/addon-docs';
2+
3+
<Meta title="Concepts/Migration/from v0/Components/Card Migration/CardFooter" />
4+
5+
# Card Footer Migration
6+
7+
## Overview
8+
9+
Before:
10+
11+
```tsx
12+
import { CardFooter } from '@fluentui/react-northstar';
13+
14+
const Component = () => <CardFooter>Lorem ipsum</CardFooter>;
15+
```
16+
17+
After:
18+
19+
```tsx
20+
import { CardFooter } from '@fluentui/react-components/unstable';
21+
22+
const Component = () => <CardFooter Footer="Lorem ipsum" />;
23+
```
24+
25+
## How to migrate props:
26+
27+
| CardFooter props | migration guide |
28+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
29+
| as, className | keep it as is |
30+
| variables, styles | see Migrate style overrides in this document |
31+
| accessibility | see [migrate-custom-accessibility.md](?path=/docs/concepts-migrating-from-v0-custom-accessibility--page). Also check the focusMode new prop |
32+
| fitted | REMOVED: By default, all Footers are fitted |
33+
34+
## Migrate style overrides
35+
36+
⚠️ **If this is your first migration**, please read [the general guide on how to migrate styles](?path=/docs/concepts-migrating-from-v0-custom-style-overrides--page).
37+
38+
### Example for migrate boolean `variables`:
39+
40+
Follow the same patterns as in the Card [migration guide](?path=/docs/concepts-migration-from-v0-components-card-migration-card--page).

‎apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardHeader.stories.mdx‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
import { Meta } from '@storybook/addon-docs';
2+
3+
<Meta title="Concepts/Migration/from v0/Components/Card Migration/CardHeader" />
4+
5+
# Card Header Migration
6+
7+
## Overview
8+
9+
Before:
10+
11+
```tsx
12+
import { CardHeader } from '@fluentui/react-northstar';
13+
14+
const Component = () => <CardHeader>Lorem ipsum</CardHeader>;
15+
```
16+
17+
After:
18+
19+
```tsx
20+
import { CardHeader } from '@fluentui/react-components/unstable';
21+
22+
const Component = () => <CardHeader header="Lorem ipsum" />;
23+
```
24+
25+
## How to migrate props:
26+
27+
| CardHeader props | migration guide |
28+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
29+
| as, className | keep it as is |
30+
| variables, styles | see Migrate style overrides in this document |
31+
| accessibility | see [migrate-custom-accessibility.md](?path=/docs/concepts-migrating-from-v0-custom-accessibility--page). Also check the focusMode new prop |
32+
| fitted | REMOVED: by default, all headers are fitted |
33+
34+
## Migrate style overrides
35+
36+
⚠️ **If this is your first migration**, please read [the general guide on how to migrate styles](?path=/docs/concepts-migrating-from-v0-custom-style-overrides--page).
37+
38+
### Example for migrate boolean `variables`:
39+
40+
Follow the same patterns as in the Card [migration guide](?path=/docs/concepts-migration-from-v0-components-card-migration-card--page).

‎apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardPreview.stories.mdx‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import { Meta } from '@storybook/addon-docs';
2+
3+
<Meta title="Concepts/Migration/from v0/Components/Card Migration/CardPreview" />
4+
5+
# Card Preview Migration
6+
7+
## Overview
8+
9+
Before:
10+
11+
```tsx
12+
import { CardPreview, Image } from '@fluentui/react-northstar';
13+
14+
const Component = () => (
15+
<CardPreview>
16+
<Image fluid src="https://url-of.the/image.jpg" alt="Preview of a Word document" />
17+
</CardPreview>
18+
);
19+
```
20+
21+
After:
22+
23+
```tsx
24+
import { CardPreview } from '@fluentui/react-components/unstable';
25+
26+
const Component = () => (
27+
<CardPreview>
28+
<img src="https://url-of.the/image.jpg" alt="Preview of a Word document" />
29+
</CardPreview>
30+
);
31+
```
32+
33+
## How to migrate props:
34+
35+
| CardPreview props | migration guide |
36+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
37+
| as, className | keep it as is |
38+
| variables, styles | see Migrate style overrides in this document |
39+
| accessibility | see [migrate-custom-accessibility.md](?path=/docs/concepts-migrating-from-v0-custom-accessibility--page). Also check the focusMode new prop |
40+
| fitted | REMOVED: by default, all Previews are fitted |
41+
| horizontal | REMOVED: no longer supported |
42+
43+
## Migrate style overrides
44+
45+
⚠️ **If this is your first migration**, please read [the general guide on how to migrate styles](?path=/docs/concepts-migrating-from-v0-custom-style-overrides--page).
46+
47+
### Example for migrate boolean `variables`:
48+
49+
Follow the same patterns as in the Card [migration guide](?path=/docs/concepts-migration-from-v0-components-card-migration-card--page).

0 commit comments

Comments
 (0)