From fcc267e3746d21a6869ef0a2180c220248adbc88 Mon Sep 17 00:00:00 2001 From: Oleksandr Fediashov Date: Mon, 7 Feb 2022 14:56:56 +0100 Subject: [PATCH 01/28] docs: notes on migration to `@fluentui/react-components@9.0.0-rc.1` --- packages/react-components/MIGRATION-NOTES.md | 25 ++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 packages/react-components/MIGRATION-NOTES.md diff --git a/packages/react-components/MIGRATION-NOTES.md b/packages/react-components/MIGRATION-NOTES.md new file mode 100644 index 00000000000000..fe1bb7973b0dbb --- /dev/null +++ b/packages/react-components/MIGRATION-NOTES.md @@ -0,0 +1,25 @@ +# Notes on migration to `@fluentui/react-components@9.0.0-rc.1` + +## Styling changes + +### Functions no longer supported + +**TBD** + +### CSS shorthands no longer supported + +**TBD** + +### makeStyles is Griffel now + +**TBD** + +## Typings & exports + +### Hooks are export with "\_unstable" suffix + +**TBD** + +### Removed functionality & exports + +**TBD** From 733a68f19d9f125db7e817bef797459ec828c4ad Mon Sep 17 00:00:00 2001 From: Oleksandr Fediashov Date: Mon, 7 Feb 2022 15:21:24 +0100 Subject: [PATCH 02/28] add notes about removed functions & useTheme() --- packages/react-components/MIGRATION-NOTES.md | 40 ++++++++++++++++++-- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/packages/react-components/MIGRATION-NOTES.md b/packages/react-components/MIGRATION-NOTES.md index fe1bb7973b0dbb..825a99c98f4d75 100644 --- a/packages/react-components/MIGRATION-NOTES.md +++ b/packages/react-components/MIGRATION-NOTES.md @@ -4,15 +4,29 @@ ### Functions no longer supported -**TBD** +Functions in `makeStyles()` are no longer supported, `tokens` can be used directly. + +Please apply following changes: + +```diff +import { makeStyles } from '@fluentui/react-componenents'; ++import { makeStyles, tokens } from '@fluentui/react-componenents'; + +const useStyles = makeStyles({ +- root: theme => ({ color: theme.tokenB }), ++ root: { color: tokens.tokenB }, +}); +``` + +For more details, please check [microsoft/fluentui#20651](https://github.com/microsoft/fluentui/pull/20651). ### CSS shorthands no longer supported **TBD** -### makeStyles is Griffel now +### makeStyles is Griffel now [just rename] -**TBD** +`makeStyles` CSS-in-JS become a separate project called [Griffel](https://github.com/microsoft/griffel). It still used in Fluent UI React v9. ## Typings & exports @@ -22,4 +36,22 @@ ### Removed functionality & exports -**TBD** +#### `useTheme()` hook is no longer exported + +To replace the hook usage please apply following changes: + +```diff +-import { useTheme } from `@fluentui/react-components`; ++import { tokens } from `@fluentui/react-components`; + +function App() { +- const theme = useTheme(); + +- return
; ++ return
; +} +``` + +> **Note**: `tokens.VALUE` returns name of a CSS variable, not an actual value. + +For more details, please check [microsoft/fluentui#21257](https://github.com/microsoft/fluentui/pull/21257). From 57399f0df3f2c4f5bd01dc5bb683e684a5a22ebc Mon Sep 17 00:00:00 2001 From: Oleksandr Fediashov Date: Mon, 7 Feb 2022 15:37:14 +0100 Subject: [PATCH 03/28] add notes about shorthands --- packages/react-components/MIGRATION-NOTES.md | 30 +++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/packages/react-components/MIGRATION-NOTES.md b/packages/react-components/MIGRATION-NOTES.md index 825a99c98f4d75..68dcb0868c7f9a 100644 --- a/packages/react-components/MIGRATION-NOTES.md +++ b/packages/react-components/MIGRATION-NOTES.md @@ -22,7 +22,35 @@ For more details, please check [microsoft/fluentui#20651](https://github.com/mic ### CSS shorthands no longer supported -**TBD** +[CSS shorthands](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties) in `makeStyles()` calls are no longer supported. For many shorthands there matching functions in `@fluentui/react-components`: + +```ts +import { shorthands } from '@fluentui/react-componenents'; + +console.log(shorthands.overflow('hidden')); // { overflowX: 'hidden', overflowY: 'hidden' } +``` + +Please apply following changes: + +```diff +import { makeStyles } from '@fluentui/react-componenents'; ++import { makeStyles, shorthands } from '@fluentui/react-componenents'; + +const useStyles = makeStyles({ +- backgroundColor: { background: 'red' }, ++ backgroundColor: { backgroundColor: 'red' }, +- padding: { padding: '5px' }, ++ padding: { ...shorthands.padding('5px') }, +- margin: { margin: '5px' }, ++ margin: { ...shorthands.margin('5px') }, +- border: { border: '5px solid red' }, ++ border: { ...shorthands.border('5px', 'solid', 'red') }, +- borderRight: { borderRight: '5px solid red' }, ++ borderRight: { ...shorthands.borderRight('5px', 'solid', 'red') }, +}); +``` + +For more details, please check [microsoft/fluentui#20573](https://github.com/microsoft/fluentui/pull/20573). ### makeStyles is Griffel now [just rename] From 6fa29161dd18adcdaa1af9530cf477957697ed37 Mon Sep 17 00:00:00 2001 From: Oleksandr Fediashov Date: Mon, 7 Feb 2022 15:58:14 +0100 Subject: [PATCH 04/28] add notes about unstable --- packages/react-components/MIGRATION-NOTES.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/packages/react-components/MIGRATION-NOTES.md b/packages/react-components/MIGRATION-NOTES.md index 68dcb0868c7f9a..0e7820d9d96e49 100644 --- a/packages/react-components/MIGRATION-NOTES.md +++ b/packages/react-components/MIGRATION-NOTES.md @@ -60,7 +60,21 @@ For more details, please check [microsoft/fluentui#20573](https://github.com/mic ### Hooks are export with "\_unstable" suffix -**TBD** +All component hooks and render functions were renamed to add the suffix `_unstable` to indicate that their API has not been finalized and may change in the future. + +```diff +-import { renderAccordionHeader } from `@fluentui/react-components`; ++import { renderAccordionHeader_unstable } from `@fluentui/react-components`; + +-useAccordionHeaderStyles(); +-renderAccordionHeader(); ++useAccordionHeaderStyles_unstable(); ++renderAccordionHeader_unstable(); +``` + +> **Note**: No changes in functionality. + +For more details, please check [microsoft/fluentui#21365](https://github.com/microsoft/fluentui/pull/21365). ### Removed functionality & exports @@ -83,3 +97,7 @@ function App() { > **Note**: `tokens.VALUE` returns name of a CSS variable, not an actual value. For more details, please check [microsoft/fluentui#21257](https://github.com/microsoft/fluentui/pull/21257). + +### Component changes + +**TBD** From 7469fcd91291647bfb30c6a43fbbcc7af81a9d85 Mon Sep 17 00:00:00 2001 From: Oleksandr Fediashov Date: Mon, 7 Feb 2022 16:01:02 +0100 Subject: [PATCH 05/28] Change files --- ...ct-components-a20ef21e-2146-4cb1-bf4b-982296a5b779.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 change/@fluentui-react-components-a20ef21e-2146-4cb1-bf4b-982296a5b779.json diff --git a/change/@fluentui-react-components-a20ef21e-2146-4cb1-bf4b-982296a5b779.json b/change/@fluentui-react-components-a20ef21e-2146-4cb1-bf4b-982296a5b779.json new file mode 100644 index 00000000000000..26f92e81203b0d --- /dev/null +++ b/change/@fluentui-react-components-a20ef21e-2146-4cb1-bf4b-982296a5b779.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "docs: notes on migration to `@fluentui/react-components@9.0.0-rc.1`", + "packageName": "@fluentui/react-components", + "email": "olfedias@microsoft.com", + "dependentChangeType": "none" +} From 26d068b6e4f43009c22e9634f87c7cd872a90d19 Mon Sep 17 00:00:00 2001 From: Ben Howell <48106640+behowell@users.noreply.github.com> Date: Tue, 8 Feb 2022 12:30:32 -0800 Subject: [PATCH 06/28] Add notes on `getSlots` and `Slot` type changes --- packages/react-components/MIGRATION-NOTES.md | 50 +++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/packages/react-components/MIGRATION-NOTES.md b/packages/react-components/MIGRATION-NOTES.md index 0e7820d9d96e49..8e54bec0f86227 100644 --- a/packages/react-components/MIGRATION-NOTES.md +++ b/packages/react-components/MIGRATION-NOTES.md @@ -98,6 +98,54 @@ function App() { For more details, please check [microsoft/fluentui#21257](https://github.com/microsoft/fluentui/pull/21257). -### Component changes +### Slot utilities have been updated and renamed + +#### The `getSlots` function has been updated + +> **Note**: This change should not affect most users of the library. It only affects authors of custom render functions. + +`getSlots` now returns `null` instead of `nullRender` for slots that don't render. This requires that the render function check for null before rendering a slot. `getSlots` also no longer takes a second parameter listing the slot names. +```diff +const renderMyComponent = (state: MyComponentState) => { +- const { slots, slotProps } = getSlots(state, ['root', 'slotA', 'slotB']); ++ const { slots, slotProps } = getSlots(state); + + return ( + +- ++ {slots.slotA && } +- ++ {slots.slotB && } + + ); +}; +``` + +#### New `Slot` type, and renamed slot utility types + +> **Note**: This change should not affect most users of the library. It only affects authors of custom components. + +All slots are now declared using a single `Slot` type: +* `IntrinsicShorthandProps` => `Slot`: direct rename with the same arguments. +* `ObjectShorthandProps` => `Slot`: the argument changes from the props type to the component type; e.g. from `ButtonProps`, to `typeof Button`. + +```diff +type MyComponentSlots = { +- root?: IntrinsicShorthandProps<'div'>; ++ root?: Slot<'div'>; +- slotA?: IntrinsicShorthandProps<'label', 'span' | 'div'>; ++ slotA?: Slot<'label', 'span' | 'div'>; +- slotB?: ObjectShorthandProps; ++ slotB?: Slot; +}; +``` + +The following types related to slots have been renamed: +* `ShorthandProps` => `WithSlotShorthandValue` +* `ShorthandRenderFunction` => `SlotRenderFunction` +* `ObjectShorthandPropsRecord` => `SlotPropsRecord` +* `DefaultObjectShorthandProps` => `UnknownSlotProps` + +## Component changes **TBD** From 4d371ee6984ffd6da28361584a18cfd2dcf1f953 Mon Sep 17 00:00:00 2001 From: Ben Howell <48106640+behowell@users.noreply.github.com> Date: Tue, 8 Feb 2022 13:10:10 -0800 Subject: [PATCH 07/28] Fix formatting --- packages/react-components/MIGRATION-NOTES.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/packages/react-components/MIGRATION-NOTES.md b/packages/react-components/MIGRATION-NOTES.md index 8e54bec0f86227..3110361ef0a2f4 100644 --- a/packages/react-components/MIGRATION-NOTES.md +++ b/packages/react-components/MIGRATION-NOTES.md @@ -105,6 +105,7 @@ For more details, please check [microsoft/fluentui#21257](https://github.com/mic > **Note**: This change should not affect most users of the library. It only affects authors of custom render functions. `getSlots` now returns `null` instead of `nullRender` for slots that don't render. This requires that the render function check for null before rendering a slot. `getSlots` also no longer takes a second parameter listing the slot names. + ```diff const renderMyComponent = (state: MyComponentState) => { - const { slots, slotProps } = getSlots(state, ['root', 'slotA', 'slotB']); @@ -126,8 +127,9 @@ const renderMyComponent = (state: MyComponentState) => { > **Note**: This change should not affect most users of the library. It only affects authors of custom components. All slots are now declared using a single `Slot` type: -* `IntrinsicShorthandProps` => `Slot`: direct rename with the same arguments. -* `ObjectShorthandProps` => `Slot`: the argument changes from the props type to the component type; e.g. from `ButtonProps`, to `typeof Button`. + +- `IntrinsicShorthandProps` => `Slot`: direct rename with the same arguments. +- `ObjectShorthandProps` => `Slot`: the argument changes from the props type to the component type; e.g. from `ButtonProps`, to `typeof Button`. ```diff type MyComponentSlots = { @@ -141,10 +143,11 @@ type MyComponentSlots = { ``` The following types related to slots have been renamed: -* `ShorthandProps` => `WithSlotShorthandValue` -* `ShorthandRenderFunction` => `SlotRenderFunction` -* `ObjectShorthandPropsRecord` => `SlotPropsRecord` -* `DefaultObjectShorthandProps` => `UnknownSlotProps` + +- `ShorthandProps` => `WithSlotShorthandValue` +- `ShorthandRenderFunction` => `SlotRenderFunction` +- `ObjectShorthandPropsRecord` => `SlotPropsRecord` +- `DefaultObjectShorthandProps` => `UnknownSlotProps` ## Component changes From c7d25ad40b84a5601b7f56019a037bbec0de8188 Mon Sep 17 00:00:00 2001 From: Ben Howell <48106640+behowell@users.noreply.github.com> Date: Tue, 8 Feb 2022 17:53:34 -0800 Subject: [PATCH 08/28] Add notes for Avatar, Icons, and Tooltip --- packages/react-components/MIGRATION-NOTES.md | 49 ++++++++++++++++++-- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/packages/react-components/MIGRATION-NOTES.md b/packages/react-components/MIGRATION-NOTES.md index 3110361ef0a2f4..74319dc6f30178 100644 --- a/packages/react-components/MIGRATION-NOTES.md +++ b/packages/react-components/MIGRATION-NOTES.md @@ -114,14 +114,16 @@ const renderMyComponent = (state: MyComponentState) => { return ( - -+ {slots.slotA && } - ++ {slots.slotA && } + {slots.slotB && } ); }; ``` +For more details, see [microsoft/fluentui#21503](https://github.com/microsoft/fluentui/pull/21503). + #### New `Slot` type, and renamed slot utility types > **Note**: This change should not affect most users of the library. It only affects authors of custom components. @@ -134,10 +136,10 @@ All slots are now declared using a single `Slot` type: ```diff type MyComponentSlots = { - root?: IntrinsicShorthandProps<'div'>; -+ root?: Slot<'div'>; - slotA?: IntrinsicShorthandProps<'label', 'span' | 'div'>; -+ slotA?: Slot<'label', 'span' | 'div'>; - slotB?: ObjectShorthandProps; ++ root?: Slot<'div'>; ++ slotA?: Slot<'label', 'span' | 'div'>; + slotB?: Slot; }; ``` @@ -151,4 +153,43 @@ The following types related to slots have been renamed: ## Component changes -**TBD** +### Avatar + +- The `label` prop has been renamed to `initials`. +- Removed the `getInitials` prop. Instead, the customized initials can be set directly on the `initials` prop: + ```diff + - + + + ``` +- The `activeAppearance` prop can no longer be `glow` or `ring-glow`. Those appearances may be added again later when they have a final visual design. + +### Icons + +- Most icons are now available without a specific size (like `` instead of ``). + - These icons will get their size from either the CSS `fontSize`, or the icon's `fontSize` property. Every FluentUI component with an `icon` slot will style these icons to be the correct size when used in that slot. + - For example, instead of having to pick the correct size icon for a Button, an icon without a specific size can be used: + ```diff + - + + +✅✅✅ + + + + + Item + Item + Item + + + + +✅✅✅ + + + + + + + + + Item + Item + Item + + + +``` ### `MenuButton` From b31a1a96e0654d45631e0c656846b25a9b04d4de Mon Sep 17 00:00:00 2001 From: Oleksandr Fediashov Date: Thu, 10 Feb 2022 16:16:06 +0100 Subject: [PATCH 22/28] add notes about *Commons type --- packages/react-components/MIGRATION-NOTES.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/packages/react-components/MIGRATION-NOTES.md b/packages/react-components/MIGRATION-NOTES.md index b3defe4f568c23..518f25803c7499 100644 --- a/packages/react-components/MIGRATION-NOTES.md +++ b/packages/react-components/MIGRATION-NOTES.md @@ -164,6 +164,14 @@ All component hooks and render functions were renamed to add the suffix `_unstab For more details, please check [microsoft/fluentui#21365](https://github.com/microsoft/fluentui/pull/21365). +### `*Commons` types are no longer exported + +```diff +-import { AvatarCommons } from '@fluentui/react-components'; +``` + +There is no direct replacement, consider to use `AvatarProps` or `AvatarState` for example. For more details, please check [microsoft/fluentui#21195](https://github.com/microsoft/fluentui/pull/21195). + ### Removed functionality & exports #### `useTheme()` hook is no longer exported @@ -302,7 +310,7 @@ The styles of the `CompoundButton` component have been updated to match the late + - - -✅✅✅ - - - - - Item - Item - Item - - - - -✅✅✅ - - - - - - - - - Item - Item - Item - - - +function App() { + return ( + <> + {/* ❌❌❌ */} + + + + Item + Item + Item + + + + + + + + {/* ✅✅✅ */} + + + + + + + Item + Item + Item + + + + + {/* ✅✅✅ */} + + + + + + + + + Item + Item + Item + + + + + ); +} ``` ### `MenuButton` From 48da5ef642a7a8a83fed0c6f6e5484df6b51468c Mon Sep 17 00:00:00 2001 From: Oleksandr Fediashov Date: Thu, 10 Feb 2022 16:19:47 +0100 Subject: [PATCH 27/28] add from --- packages/react-components/MIGRATION-NOTES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-components/MIGRATION-NOTES.md b/packages/react-components/MIGRATION-NOTES.md index fef627d696b864..15cbf9f11e2373 100644 --- a/packages/react-components/MIGRATION-NOTES.md +++ b/packages/react-components/MIGRATION-NOTES.md @@ -1,4 +1,4 @@ -# Notes on migration to `@fluentui/react-components@9.0.0-rc.1` +# Notes on migration to `@fluentui/react-components@9.0.0-rc.1` from `9.0.0-beta.5` ## Changes to the styling system From 33092ce3aae04e154fe57be9318d6151488309b3 Mon Sep 17 00:00:00 2001 From: Oleksandr Fediashov Date: Thu, 10 Feb 2022 16:20:58 +0100 Subject: [PATCH 28/28] Update packages/react-components/MIGRATION-NOTES.md Co-authored-by: ling1726 --- packages/react-components/MIGRATION-NOTES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-components/MIGRATION-NOTES.md b/packages/react-components/MIGRATION-NOTES.md index 15cbf9f11e2373..a7bc38694c57c2 100644 --- a/packages/react-components/MIGRATION-NOTES.md +++ b/packages/react-components/MIGRATION-NOTES.md @@ -1,4 +1,4 @@ -# Notes on migration to `@fluentui/react-components@9.0.0-rc.1` from `9.0.0-beta.5` +# Migration notes from `@fluentui/react-components@9.0.0-beta.5`to `@fluentui/react-components@9.0.0-rc.1` ## Changes to the styling system