diff --git a/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.Card.stories.mdx b/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.Card.stories.mdx new file mode 100644 index 00000000000000..811fa3af181b20 --- /dev/null +++ b/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.Card.stories.mdx @@ -0,0 +1,227 @@ +import { Meta } from '@storybook/addon-docs'; + + + +# Card Migration + +## Overview + +Before: + +```tsx +import { Card } from '@fluentui/react-northstar'; +const Component = () => Lorem ipsum, dolor sit amet consectetur adipisicing elit.; +``` + +After: + +```tsx +import { Card } from '@fluentui/react-components/unstable'; +const Component = () => Lorem ipsum, dolor sit amet consectetur adipisicing elit.; +``` + +## How to migrate props: + +| Card props | migration guide | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| as, className | keep it as is | +| variables, styles | see Migrate style overrides in this document | +| accessibility | see [migrate-custom-accessibility.md](?path=/docs/concepts-migrating-from-v0-custom-accessibility--page). Also check the focusMode new prop | +| centered | REMOVED: see Migrate centered prop in this document | +| compact | use `size="small"` | +| disabled | REMOVED: No equivalent functionality. Can be created by overriding the styles. | +| elevated | REMOVED: All cards are now elevated by default. To change that, use the `appearance` property. | +| expandable | REMOVED: No equivalent functionality. | +| fluid | REMOVED: see Migrate fluid prop in this document | +| ghost | use `appearance="subtle"` | +| inverted | use `appearance="filled-alternative"` | +| size | keep it as is. Values: `small`, `medium`(default) and `large` | + +## Migrate style overrides + +⚠️ **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). + +### Example for migrate boolean `variables`: + +Before: + +```tsx +// in COMPONENT_NAME.tsx +import { Card } from '@fluentui/react-northstar'; + +export const Component = () => ; + +// in Card-styles.ts +export const CardStyles1 = { + root: ({ variables: { isActionCard } }) => ({ + ...(isActionCard && { + color: colors.grey['250'], + }), + }), +}; +``` + +After: + +```tsx +// in COMPONENT_NAME.tsx +import { Card } from '@fluentui/react-components/unstable'; +import { useStyles } from './COMPONENT_NAME.styles.ts'; + +export const Component = () => { + const classes = useStyles(); + + return ; +}; + +// in COMPONENT_NAME.styles.ts +import { makeStyles, tokens } from '@fluentui/react-components/unstable'; + +export const useStyles = makeStyles({ + actionCard: { + color: colors.colorNeutralForeground1, + }, +}); +``` + +### Example for migrate namespaced styles, with conditional styles via `variableProps`: + +Before: + +```tsx +// in COMPONENT_NAME.tsx +import { Card, useUIProviderContext } from '@fluentui/react-northstar'; + +export const Component = props => { + const { vars } = useUIProviderContext(); + const { enableUsingChatListGroupTitleAsHeader } = props; + return ( + + ); +}; + +// in Card-namespace-flyout.ts +export default { + root: { + filterCard: ({ variableProps: { enableUsingChatListGroupTitleAsHeader } }) => ({ + ...(enableUsingChatListGroupTitleAsHeader && { + height: '3rem', + width: '8rem', + minWidth: '8rem', + }), + }), + }, +}; +``` + +After: + +```tsx +// in COMPONENT_NAME.tsx +import { Card, mergeClasses } from '@fluentui/react-components/unstable'; +import { useStyles } from './COMPONENT_NAME.styles.ts'; + +export const Component = props => { + const classes = useStyles(); + + return ( + + ); +}; + +// in COMPONENT_NAME.styles.ts +import { makeStyles } from '@fluentui/react-components/unstable'; + +export const useStyles = makeStyles({ + chatListGroupTitleAsHeader: { + height: '3rem', + width: '8rem', + minWidth: '8rem', + }, +}); +``` + +## Migrate `centered` prop + +Can be achieved by overriding the styles of the Card component. + +Before: + +```tsx +import { Card } from '@fluentui/react-northstar'; + +const Component = () => Lorem ipsum, dolor sit amet consectetur adipisicing elit.; +``` + +After: + +```tsx +import * as React from 'react'; +import { makeStyles } from '@fluentui/react-components/unstable'; +import { Card } from '@fluentui/react-components/unstable'; + +const useStyles = makeStyles({ + centeredCard: { + justifyItems: 'center', + }, +}); + +export const CenteredCard = () => { + const styles = useStyles(); + + return ( + +

Lorem ipsum dolor sit amet.

+
+ ); +}; +``` + +## Migrate `size` prop + +All cards are fluid by default. To change that, use a parent container with a defined size. + +Before: + +```tsx +import { Card } from '@fluentui/react-northstar'; + +const Component = () => Lorem ipsum, dolor sit amet consectetur adipisicing elit.; +``` + +After: + +```jsx +import * as React from 'react'; +import { makeStyles } from '@fluentui/react-components/unstable'; +import { Card } from '@fluentui/react-components/unstable'; + +const useStyles = makeStyles({ + parent: { + width: '500px', + }, +}); + +export const SizedCard = () => { + const styles = useStyles(); + + return ( +
+ +

Lorem ipsum dolor sit amet.

+
+
+ ); +}; +``` diff --git a/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardBody.stories.mdx b/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardBody.stories.mdx new file mode 100644 index 00000000000000..fabc5c78b04f23 --- /dev/null +++ b/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardBody.stories.mdx @@ -0,0 +1,35 @@ +import { Meta } from '@storybook/addon-docs'; + + + +# Card Body Migration + +## Overview + +This component is not needed anymore. Instead, pass any content under the main Card component. + +Before: + +```jsx +import { Card, CardBody } from '@fluentui/react-northstar'; + +export const CardBodyExample = () => ( + + +

Lorem ipsum dolor sit amet.

+
+
+); +``` + +After: + +```jsx +import { Card } from '@fluentui/react-components/unstable'; + +export const CardBodyExample = () => ( + +

Lorem ipsum dolor sit amet.

+
+); +``` diff --git a/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardFooter.stories.mdx b/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardFooter.stories.mdx new file mode 100644 index 00000000000000..f4a6881242dfb4 --- /dev/null +++ b/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardFooter.stories.mdx @@ -0,0 +1,40 @@ +import { Meta } from '@storybook/addon-docs'; + + + +# Card Footer Migration + +## Overview + +Before: + +```tsx +import { CardFooter } from '@fluentui/react-northstar'; + +const Component = () => Lorem ipsum; +``` + +After: + +```tsx +import { CardFooter } from '@fluentui/react-components/unstable'; + +const Component = () => ; +``` + +## How to migrate props: + +| CardFooter props | migration guide | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| as, className | keep it as is | +| variables, styles | see Migrate style overrides in this document | +| accessibility | see [migrate-custom-accessibility.md](?path=/docs/concepts-migrating-from-v0-custom-accessibility--page). Also check the focusMode new prop | +| fitted | REMOVED: By default, all Footers are fitted | + +## Migrate style overrides + +⚠️ **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). + +### Example for migrate boolean `variables`: + +Follow the same patterns as in the Card [migration guide](?path=/docs/concepts-migration-from-v0-components-card-migration-card--page). diff --git a/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardHeader.stories.mdx b/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardHeader.stories.mdx new file mode 100644 index 00000000000000..c1e2c5b9fb92eb --- /dev/null +++ b/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardHeader.stories.mdx @@ -0,0 +1,40 @@ +import { Meta } from '@storybook/addon-docs'; + + + +# Card Header Migration + +## Overview + +Before: + +```tsx +import { CardHeader } from '@fluentui/react-northstar'; + +const Component = () => Lorem ipsum; +``` + +After: + +```tsx +import { CardHeader } from '@fluentui/react-components/unstable'; + +const Component = () => ; +``` + +## How to migrate props: + +| CardHeader props | migration guide | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| as, className | keep it as is | +| variables, styles | see Migrate style overrides in this document | +| accessibility | see [migrate-custom-accessibility.md](?path=/docs/concepts-migrating-from-v0-custom-accessibility--page). Also check the focusMode new prop | +| fitted | REMOVED: by default, all headers are fitted | + +## Migrate style overrides + +⚠️ **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). + +### Example for migrate boolean `variables`: + +Follow the same patterns as in the Card [migration guide](?path=/docs/concepts-migration-from-v0-components-card-migration-card--page). diff --git a/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardPreview.stories.mdx b/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardPreview.stories.mdx new file mode 100644 index 00000000000000..1ef2a8f250614d --- /dev/null +++ b/apps/public-docsite-v9/src/Concepts/Migration/FromV0/Components/Card.CardPreview.stories.mdx @@ -0,0 +1,49 @@ +import { Meta } from '@storybook/addon-docs'; + + + +# Card Preview Migration + +## Overview + +Before: + +```tsx +import { CardPreview, Image } from '@fluentui/react-northstar'; + +const Component = () => ( + + Preview of a Word document + +); +``` + +After: + +```tsx +import { CardPreview } from '@fluentui/react-components/unstable'; + +const Component = () => ( + + Preview of a Word document + +); +``` + +## How to migrate props: + +| CardPreview props | migration guide | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| as, className | keep it as is | +| variables, styles | see Migrate style overrides in this document | +| accessibility | see [migrate-custom-accessibility.md](?path=/docs/concepts-migrating-from-v0-custom-accessibility--page). Also check the focusMode new prop | +| fitted | REMOVED: by default, all Previews are fitted | +| horizontal | REMOVED: no longer supported | + +## Migrate style overrides + +⚠️ **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). + +### Example for migrate boolean `variables`: + +Follow the same patterns as in the Card [migration guide](?path=/docs/concepts-migration-from-v0-components-card-migration-card--page). diff --git a/change/@fluentui-react-card-0733d20c-4e51-4fbe-bf8b-27ce512bef04.json b/change/@fluentui-react-card-0733d20c-4e51-4fbe-bf8b-27ce512bef04.json new file mode 100644 index 00000000000000..0ef3c4058b73b3 --- /dev/null +++ b/change/@fluentui-react-card-0733d20c-4e51-4fbe-bf8b-27ce512bef04.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "docs: add migration guide for cards from V0 to V9", + "packageName": "@fluentui/react-card", + "email": "marcosvmmoura@gmail.com", + "dependentChangeType": "none" +} diff --git a/packages/react-components/react-card/docs/MIGRATION.md b/packages/react-components/react-card/docs/MIGRATION.md deleted file mode 100644 index 41380ad5de49cf..00000000000000 --- a/packages/react-components/react-card/docs/MIGRATION.md +++ /dev/null @@ -1,323 +0,0 @@ -- [Migration from v0](#migration-from-v0) - - [Card](#card) - - [Property Mapping](#property-mapping) - - [Props that remain as is](#props-that-remain-as-is) - - [Props no longer supported with an equivalent functionality](#props-no-longer-supported-with-an-equivalent-functionality) - - [Props no longer supported](#props-no-longer-supported) - - [CardHeader](#cardheader) - - [Property Mapping](#property-mapping-1) - - [Props that remain as is](#props-that-remain-as-is-1) - - [Props no longer supported with an equivalent functionality](#props-no-longer-supported-with-an-equivalent-functionality-1) - - [Props no longer supported](#props-no-longer-supported-1) - - [CardBody](#cardbody) - - [CardPreview](#cardpreview) - - [Property Mapping](#property-mapping-2) - - [Props that remain as is](#props-that-remain-as-is-2) - - [Props no longer supported with an equivalent functionality](#props-no-longer-supported-with-an-equivalent-functionality-2) - - [Props no longer supported](#props-no-longer-supported-2) - - [Example](#example) - - [Before](#before) - - [After](#after) - - [CardColumn](#cardcolumn) - - [CardExpandableBox](#cardexpandablebox) - - [CardTopControls](#cardtopcontrols) - - [CardFooter](#cardfooter) - - [Property Mapping](#property-mapping-3) - - [Props that remain as is](#props-that-remain-as-is-3) - - [Props no longer supported with an equivalent functionality](#props-no-longer-supported-with-an-equivalent-functionality-3) - - [Props no longer supported](#props-no-longer-supported-3) -- [Migration from v8](#migration-from-v8) - -# Migration from v0 - -## Card - -### Property Mapping - -| v0 - `Card` | v9 - `Card` | -| -------------- | ------------- | -| `acessibility` | - | -| - | `appearance` | -| `as` | `as` | -| `centered` | - | -| `className` | `className` | -| `compact` | - | -| `design` | - | -| `disabled` | - | -| `elevated` | - | -| `expandable` | - | -| `fluid` | - | -| - | `focusMode` | -| `ghost` | - | -| `inverted` | - | -| `key` | - | -| - | `orientation` | -| `ref` | - | -| - | `root` slot | -| `selected` | - | -| `size` | `size` | -| `styles` | - | -| `variables` | - | - -### Props that remain as is - -- `as` -- `className` -- `key` -- `ref` -- `size` => The size options are now reduced: `'small' | 'medium' | 'large'` - -### Props no longer supported with an equivalent functionality - -- `accessibility` => Override accessibility behavior by composing the `Card` how you want -- `compact` => Instead, use `size="small"` -- `ghost` => Instead, use `appearance="subtle"` -- `inverted` => Instead, use `appearance="filled-alternative"` - -### Props no longer supported - -- `centered` => Can be achieved by overriding the styles of the Card component: - -```jsx -import * as React from 'react'; -import { makeStyles } from '@fluentui/react-components'; -import { Card } from '@fluentui/react-components/unstable'; - -const useStyles = makeStyles({ - centeredCard: { - justifyItems: 'center', - }, -}); - -export const CenteredCard = () => { - const styles = useStyles(); - - return ( - -

Lorem ipsum dolor sit amet.

-
- ); -}; -``` - -- `disabled` => No equivalent functionality. Can be created by overriding the styles. -- `elevated` => All cards are now elevated by default. To change that, use the `appearance` property. -- `expandable` => No equivalent functionality. -- `fluid` => All cards are fluid by default. To change that, use a parent container with a defined size: - -```jsx -import * as React from 'react'; -import { makeStyles } from '@fluentui/react-components'; -import { Card } from '@fluentui/react-components/unstable'; - -const useStyles = makeStyles({ - parent: { - width: '500px', - }, -}); - -export const SizedCard = () => { - const styles = useStyles(); - - return ( -
- -

Lorem ipsum dolor sit amet.

-
-
- ); -}; -``` - -- `selected` => No equivalent functionality. - -## CardHeader - -### Property Mapping - -| v0 - `Cardheader` | v9 - `Cardheader` | -| ----------------- | ------------------ | -| `acessibility` | - | -| - | `root` slot | -| - | `image` slot | -| - | `header` slot | -| - | `description` slot | -| - | `action` slot | -| `as` | - | -| `className` | - | -| `design` | - | -| `fitted` | - | -| `key` | - | -| `ref` | - | -| `styles` | - | -| `variables` | - | - -### Props that remain as is - -- `as` -- `className` -- `key` -- `ref` - -### Props no longer supported with an equivalent functionality - -- `accessibility` => Override accessibility behavior by composing the `CardHeader` how you want - -### Props no longer supported - -- `design` -- `fitted` -- `styles` -- `variables` - -## CardBody - -This component is no longer supported. Instead, pass any content under the main Card component. - -Before: - -```jsx -import * as React from 'react'; -import { Card, CardBody } from '@fluentui/react-northstar'; - -export const CardBodyExample = () => ( - - -

Lorem ipsum dolor sit amet.

-
-
-); -``` - -After: - -```jsx -import * as React from 'react'; -import { Card } from '@fluentui/react-components/unstable'; - -export const CardBodyExample = () => ( - -

Lorem ipsum dolor sit amet.

-
-); -``` - -## CardPreview - -### Property Mapping - -| v0 - `CardPreview` | v9 - `CardPreview` | -| ------------------ | ------------------ | -| `acessibility` | - | -| `as` | - | -| `className` | - | -| `design` | - | -| `fitted` | - | -| `horizontal` | - | -| - | `logo` slot | -| `key` | - | -| `ref` | - | -| - | `root` slot | -| `styles` | - | -| `variables` | - | - -### Props that remain as is - -- `as` -- `className` -- `key` -- `ref` - -### Props no longer supported with an equivalent functionality - -- `accessibility` => Override accessibility behavior by composing the `CardPreview` how you want - -### Props no longer supported - -- `design` -- `fitted` -- `horizontal` -- `styles` -- `variables` - -### Example - -#### Before - -```jsx -import * as React from 'react'; -import { Card, CardPreview, Image } from '@fluentui/react-northstar'; - -export const CardPreviewExample = () => ( - - - Preview of a Word document - - -); -``` - -#### After - -```jsx -import * as React from 'react'; -import { Card, CardPreview } from '@fluentui/react-components/unstable'; - -export const CardPreviewExample = () => ( - - - Preview of a Word document - - -); -``` - -## CardColumn - -This component is no longer supported. - -## CardExpandableBox - -This component is no longer supported. - -## CardTopControls - -This component is no longer supported. - -## CardFooter - -### Property Mapping - -| v0 - `CardFooter` | v9 - `CardFooter` | -| ----------------- | ----------------- | -| `acessibility` | - | -| `as` | - | -| `className` | - | -| `design` | - | -| `fitted` | - | -| `key` | - | -| `ref` | - | -| `styles` | - | -| `variables` | - | - -### Props that remain as is - -- `as` -- `className` -- `key` -- `ref` - -### Props no longer supported with an equivalent functionality - -- `accessibility` => Override accessibility behavior by composing the `CardFooter` how you want - -### Props no longer supported - -- `design` -- `fitted` -- `styles` -- `variables` - -# Migration from v8 - -WIP