From 4333a19afdf24fae44fd845b67121100dff9349f Mon Sep 17 00:00:00 2001 From: GeoffCoxMSFT Date: Sat, 4 Mar 2023 14:56:57 -0800 Subject: [PATCH 1/2] Added documentation about custom style hooks --- .../KeepingDesignConsistent.stories.mdx | 42 ++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/apps/public-docsite-v9/src/Concepts/Migration/KeepingDesignConsistent.stories.mdx b/apps/public-docsite-v9/src/Concepts/Migration/KeepingDesignConsistent.stories.mdx index 1780bffbb179a2..e2948a15f7ab67 100644 --- a/apps/public-docsite-v9/src/Concepts/Migration/KeepingDesignConsistent.stories.mdx +++ b/apps/public-docsite-v9/src/Concepts/Migration/KeepingDesignConsistent.stories.mdx @@ -102,7 +102,7 @@ As detailed in the _/Concepts/Developer/Styling Components_ topic, you can creat If you do create custom styles, we strongly recommend using design tokens. This ensures styles update with theme changes. -## You can recompose components with custom styles +## You can recompose components with different styles Fluent v9 has a powerful composition model using React hooks. Each component is separated into a hook that maps props to state, a hook that uses state to set className styles on each slot, and a render function that outputs each slot with applied props. @@ -145,3 +145,43 @@ export const MyButton: ForwardRefComponent = React.forwardRef((prop ``` This is the most advanced form of customization in Fluent UI React v9, but provides you complete control over components. + +## You can set custom style hooks per component type + +**⚠ Avoid custom style hooks** + +Prefer creating custom themes, setting className, replacing slots, extendeding theme tokens, and component recomposition. +This approach is meant as an escape-hatch when all other customizations don't work. + +**⚠ Be careful ** + +- Never change any state properties other than `className`. +- Never dynamically change hooks at runtime. This will lead to unstable hook calls. +- Custom style hooks are called from within the component and receive the component state. + Be judicious with creating styles and making `mergeClasses` call as you may affect the performance. + +You can pass `FluentProvider.customStyleHooks_unstable` a set of custom style hooks. +Each custom style hook can update root or slot class names. + +```tsx +const myButtonStyles = makeStyles({ + root: { + //... + }, +}); + +const myCustomStyles: FluentProviderCustomStyleHooks = { + useButtonStyles_unstable: state => { + const myButtonStyles = useMyButtonStyles(); + const buttonState = state as ButtonState; + buttonState.root.className = mergeClasses(buttonState.root.className, myButtonStyles.root); + }, +}; + +; +``` + +To override existing styles, use `makeStyles` to create your custom styles and then call `mergeClasses`. +To completely replace existing styles, overwrite `className`. + +When `FluentProvider` are nested, custom style hooks will be shallow merged. From f291f5da2bb9e404fef1d0a9b4a74ff1504c584a Mon Sep 17 00:00:00 2001 From: "Geoff Cox (Microsoft)" Date: Tue, 14 Mar 2023 09:41:15 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Makoto Morimoto --- .../Migration/KeepingDesignConsistent.stories.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/public-docsite-v9/src/Concepts/Migration/KeepingDesignConsistent.stories.mdx b/apps/public-docsite-v9/src/Concepts/Migration/KeepingDesignConsistent.stories.mdx index e2948a15f7ab67..2c25885c696e1b 100644 --- a/apps/public-docsite-v9/src/Concepts/Migration/KeepingDesignConsistent.stories.mdx +++ b/apps/public-docsite-v9/src/Concepts/Migration/KeepingDesignConsistent.stories.mdx @@ -150,17 +150,17 @@ This is the most advanced form of customization in Fluent UI React v9, but provi **⚠ Avoid custom style hooks** -Prefer creating custom themes, setting className, replacing slots, extendeding theme tokens, and component recomposition. -This approach is meant as an escape-hatch when all other customizations don't work. +Prefer creating custom themes, setting className, replacing slots, extending theme tokens, and component recomposition. +This approach is meant as an escape-hatch when all other customizations are not enough for your use case. **⚠ Be careful ** - Never change any state properties other than `className`. - Never dynamically change hooks at runtime. This will lead to unstable hook calls. - Custom style hooks are called from within the component and receive the component state. - Be judicious with creating styles and making `mergeClasses` call as you may affect the performance. +- Be judicious with creating styles and making `mergeClasses` call as you may affect the performance. -You can pass `FluentProvider.customStyleHooks_unstable` a set of custom style hooks. +You can pass `FluentProvider.customStyleHooks_unstable` a set of custom style hooks. The custom style hooks are considered unstable and the API may change at any time. Each custom style hook can update root or slot class names. ```tsx @@ -181,7 +181,7 @@ const myCustomStyles: FluentProviderCustomStyleHooks = { ; ``` -To override existing styles, use `makeStyles` to create your custom styles and then call `mergeClasses`. -To completely replace existing styles, overwrite `className`. +To override existing styles, use `makeStyles` to create your custom styles and then call `mergeClasses` with state `className` and the your new styles. +To completely replace existing styles, overwrite the state `className`. When `FluentProvider` are nested, custom style hooks will be shallow merged.