Skip to content

Commit 2ababec

Browse files
fabiofranzinifabiofranzini
committed
Added 'EnhancedThemeProvider' Control
1 parent d3294b0 commit 2ababec

20 files changed

+780
-1
lines changed

‎docs/documentation/docs/assets/EnhancedThemeProviderSharePoint.gif

14.3 MB
Loading

‎docs/documentation/docs/assets/EnhancedThemeProviderTeams.gif

18.6 MB
Loading

‎docs/documentation/docs/controls/EnhancedThemeProvider.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Enhanced Theme Provider
2+
3+
The reasons behind this control are many and concern the use of Fluent UI controls currently officially supported by SPFx, that is:
4+
- `Problems with Teams theme support`, when hosting a Web Part like Tab or Personal App and specifically the lack of support by this version of Fluent UI React of the high contrast theme.
5+
- `Lack of basic style`, such as fonts, for basic HTML elements when creating `Web Parts hosted in Teams as Tabs or personal App`.
6+
- Lack of basic style, such as fonts, for basic HTML elements when creating `Web Parts in "isDomainIsolated" mode`, aka the Isolated Web Parts.
7+
8+
Therefore, the control is to be considered as a sort of `wrapper for all react and non-react controls` that you want to add to the WebPart.
9+
10+
The control `extends the functionality of the Fluent UI ThemeProvider control` (currently in version 7) by adding some logic thanks to the information contained in the 'context' property, that is:
11+
- If the Web Part is hosted inside SharePoint, the theme passed through the 'Theme' property will be used or the default one of the current site will be taken.
12+
- If the web part is hosted within Teams, the "Theme" property will be ignored and using the "Context" property checks which theme is currently applied and adds a handler to notify when the theme is changed. This allows you to manage the change of theme in Teams in real-time, without having to reload the Tab or the Personal App.
13+
14+
Example of use in SharePoint in a `SharePointFullPage - Isolated web parts` (note that the titles H1, H2, H3 and the paragraph are normal html tags that automatically take the font and color style from the control):
15+
![Enhanced Theme Provider - SharePointFullPage - Isolated web parts](../assets/EnhancedThemeProviderSharePoint.gif)
16+
17+
As for Teams, given the inconsistency of the theme system of Fluent UI NorthStar (used in Teams) and Fluent UI React (used by SPFx), the themes are "emulated".
18+
19+
The control contains the refining of Teams' `Default`, `Dark` and `Hight Contrast` themes.
20+
21+
The `Default` and `Dark themes` were created simply using the Fluent UI Themes designer and the primary colors of their corresponding Teams themes.
22+
23+
For the `Hight Contrast` theme, on the other hand, given the complexity of creating a completely new theme and above all in Hight Contrast mode (neither supported nor gives SharePoint nor gives Fluent UI v7), it was decided to create the theme by hand and support only "main controls".
24+
25+
`This means that this theme is not perfect and above all not all controls will be displayed correctly.`
26+
27+
This is not a big deal, as the same theme provided by SharePoint has the same problems, it does not support Hight Contrast rendering for all controls.
28+
29+
For the `Hight Contrast` theme (in Teams), only these controls are supported by this control: `ChoiceGroup, Checkbox, ComboBox, DatePicker, SpinButton, TextField, Toggle, PrimaryButton, DefaultButton, CompoundButton, IconButton`, other fluent controls may have color rendering problems.
30+
31+
Example of use in Teams as a `TeamsPersonalApp` (note that the titles H1, H2, H3 and the paragraph are normal html tags that automatically take the font and color style from the control):
32+
![Enhanced Theme Provider - TeamsPersonalApp / TeamsTab](../assets/EnhancedThemeProviderTeams.gif)
33+
34+
## How to use this control in your solutions
35+
36+
- Check that you installed the `@pnp/spfx-controls-react` dependency. Check out the [getting started](../../#getting-started) page for more information about installing the dependency.
37+
- In your component file, import the `EnhancedThemeProvider` control as follows:
38+
39+
```TypeScript
40+
import { EnhancedThemeProvider, getDefaultTheme, useTheme, ThemeContext } from "@pnp/spfx-controls-react/lib/EnhancedThemeProvider";
41+
```
42+
43+
- Example on use the `EnhancedThemeProvider` control with only required properties:
44+
45+
```TypeScript
46+
<EnhancedThemeProvider context={this.props.context}>
47+
{/* controls to apply the theme to */}
48+
</EnhancedThemeProvider>
49+
```
50+
51+
- Example on use the `EnhancedThemeProvider` control with the most important properties:
52+
53+
```TypeScript
54+
<EnhancedThemeProvider applyTo="element" context={this.props.context} theme={this.props.themeVariant}>
55+
{/* controls to apply the theme to */}
56+
</EnhancedThemeProvider>
57+
```
58+
59+
The control provides the passage and/or creation of the theme according to what has been said before.
60+
In order to access the theme, from child controls, there are two modes, one for function-based controls, one for class-based controls.
61+
62+
- Access the theme from the child control using a function component:
63+
```TypeScript
64+
export const ChildFunctionComponent = () => {
65+
const theme = useTheme();
66+
67+
return (
68+
<DefaultButton theme={theme}>Example Child Control</DefaultButton>
69+
);
70+
}
71+
```
72+
73+
- Access the theme from the child control using a class component:
74+
```TypeScript
75+
export class ChildClassComponent extends React.Component {
76+
public render() {
77+
return (
78+
<ThemeContext.Consumer>
79+
{theme =>
80+
<DefaultButton theme={theme}>Example Child Control</DefaultButton>
81+
}
82+
</ThemeContext.Consumer>
83+
)
84+
}
85+
};
86+
```
87+
88+
- Usage example using theme in child controls:
89+
```TypeScript
90+
<EnhancedThemeProvider applyTo="element" context={this.props.context} theme={this.props.themeVariant}>
91+
<ChildFunctionComponent />
92+
<ChildClassComponent />
93+
</EnhancedThemeProvider>
94+
```
95+
96+
## Implementation
97+
98+
The `EnhancedThemeProvider` control can be configured with the following properties:
99+
100+
| Property | Type | Required | Description |
101+
| ---- | ---- | ---- | ---- |
102+
| context | WebPartContext | yes | Set the context from the SPFx Web Part. |
103+
| as | React.ElementType | no | A component that should be used as the root element of the ThemeProvider component. |
104+
| ref | React.Ref<HTMLElement> | no | Optional ref to the root element. |
105+
| theme | PartialTheme \| Theme | no | Defines the theme provided by the user. |
106+
| renderer | StyleRenderer | no | Optional interface for registering dynamic styles. Defaults to using `merge-styles`. Use this to opt into a particular rendering implementation, such as `emotion`, `styled-components`, or `jss`. Note: performance will differ between all renders. Please measure your scenarios before using an alternative implementation. |
107+
| applyTo | 'element' \| 'body' \| 'none' | no | Defines where body-related theme is applied to. Setting to 'element' will apply body styles to the root element of ThemeProvider. Setting to 'body' will apply body styles to document body. Setting to 'none' will not apply body styles to either element or body.|
108+
109+
![](https://telemetry.sharepointpnp.com/sp-dev-fx-controls-react/wiki/controls/EnhancedThemeProvider)

‎src/EnhancedThemeProvider.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
export * from './controls/EnhancedThemeProvider/index';

‎src/common/fluentUITeamsThemes/FluentUITeamsDarkTheme.ts

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import { createTheme } from "office-ui-fabric-react/lib/Styling";
2+
3+
export const fluentUITeamsDarkTheme = createTheme({
4+
...{
5+
palette: {
6+
"themePrimary": "#7f85f5",
7+
"themeLighterAlt": "#05050a",
8+
"themeLighter": "#141527",
9+
"themeLight": "#262849",
10+
"themeTertiary": "#4c5093",
11+
"themeSecondary": "#7075d7",
12+
"themeDarkAlt": "#8c91f6",
13+
"themeDark": "#9da2f7",
14+
"themeDarker": "#b6baf9",
15+
"neutralLighterAlt": "#282828",
16+
"neutralLighter": "#313131",
17+
"neutralLight": "#3f3f3f",
18+
"neutralQuaternaryAlt": "#484848",
19+
"neutralQuaternary": "#4f4f4f",
20+
"neutralTertiaryAlt": "#6d6d6d",
21+
"neutralTertiary": "#c8c8c8",
22+
"neutralSecondary": "#d0d0d0",
23+
"neutralPrimaryAlt": "#dadada",
24+
"neutralPrimary": "#ffff",
25+
"neutralDark": "#f4f4f4",
26+
"black": "#ffffff",
27+
"white": "#1f1f1f"
28+
}
29+
}
30+
});

‎src/common/fluentUITeamsThemes/FluentUITeamsDefaultTheme.ts

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import { createTheme } from "office-ui-fabric-react/lib/Styling";
2+
3+
export const fluentUITeamsDefaultTheme = createTheme({
4+
...{
5+
palette: {
6+
"themePrimary": "#6264A7",
7+
"themeLighterAlt": "#f7f7fb",
8+
"themeLighter": "#e1e1f1",
9+
"themeLight": "#c8c9e4",
10+
"themeTertiary": "#989ac9",
11+
"themeSecondary": "#7173b0",
12+
"themeDarkAlt": "#585a95",
13+
"themeDark": "#4a4c7e",
14+
"themeDarker": "#37385d",
15+
"neutralLighterAlt": "#eeeeee",
16+
"neutralLighter": "#eaeaea",
17+
"neutralLight": "#e1e1e1",
18+
"neutralQuaternaryAlt": "#d1d1d1",
19+
"neutralQuaternary": "#c8c8c8",
20+
"neutralTertiaryAlt": "#c0c0c0",
21+
"neutralTertiary": "#acacac",
22+
"neutralSecondary": "#919191",
23+
"neutralPrimaryAlt": "#767676",
24+
"neutralPrimary": "#0b0b0b",
25+
"neutralDark": "#404040",
26+
"black": "#252525",
27+
"white": "#F5F5F5"
28+
}
29+
}
30+
});

‎src/common/fluentUITeamsThemes/FluentUITeamsHighContrastTheme.ts

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
import { createTheme } from "office-ui-fabric-react/lib/Styling";
2+
import { HightContrastPalette, HightContrastSemanticColors } from "./HightContrastCustomizations/HightContrastCustomizations";
3+
import { ChoiceGroupOptionStyles } from "./HightContrastCustomizations/Styles/ChoiceGroupOption.Styles";
4+
import { DatePickerStyles } from "./HightContrastCustomizations/Styles/DatePicker.Styles";
5+
import { IconButtonStyles } from "./HightContrastCustomizations/Styles/IconButton.Styles";
6+
import { ToggleStyles } from "./HightContrastCustomizations/Styles/Toggle.styles";
7+
8+
export const fluentUITeamsHighContrastTheme = createTheme({
9+
palette: HightContrastPalette,
10+
semanticColors: HightContrastSemanticColors,
11+
isInverted: true,
12+
});
13+
14+
const hightContrastComponentStyles = {
15+
DatePicker: {
16+
styles: DatePickerStyles,
17+
},
18+
IconButton: {
19+
styles: IconButtonStyles(fluentUITeamsHighContrastTheme)
20+
},
21+
ChoiceGroupOption: {
22+
styles: ChoiceGroupOptionStyles,
23+
},
24+
Toggle: {
25+
styles: ToggleStyles,
26+
}
27+
};
28+
29+
fluentUITeamsHighContrastTheme.components = hightContrastComponentStyles;

‎src/common/fluentUITeamsThemes/HightContrastCustomizations/HightContrastCustomizations.ts

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
import { IPalette, ISemanticColors } from 'office-ui-fabric-react/lib/Styling';
2+
3+
export namespace HightContrastBaseColors {
4+
export const YELLOW = "#ffff00";
5+
export const BLUE = "#1aebff";
6+
export const GREEN = "#3ff23f";
7+
export const WHITE = "#ffffff";
8+
export const BLACK = "#000000";
9+
}
10+
11+
export const HightContrastPalette: Partial<IPalette> = {
12+
themeDarker: HightContrastBaseColors.YELLOW,
13+
themeDark: HightContrastBaseColors.YELLOW,
14+
themeDarkAlt: HightContrastBaseColors.YELLOW,
15+
themePrimary: HightContrastBaseColors.BLUE,
16+
themeSecondary: HightContrastBaseColors.YELLOW,
17+
themeTertiary: HightContrastBaseColors.GREEN,
18+
themeLight: HightContrastBaseColors.BLUE,
19+
themeLighter: HightContrastBaseColors.BLUE,
20+
themeLighterAlt: HightContrastBaseColors.BLUE,
21+
neutralDark: HightContrastBaseColors.BLACK,
22+
neutralPrimary: HightContrastBaseColors.WHITE,
23+
neutralPrimaryAlt: HightContrastBaseColors.WHITE,
24+
neutralSecondary: HightContrastBaseColors.WHITE,
25+
neutralSecondaryAlt: HightContrastBaseColors.WHITE,
26+
neutralTertiary: HightContrastBaseColors.WHITE,
27+
neutralTertiaryAlt: HightContrastBaseColors.WHITE,
28+
neutralQuaternary: HightContrastBaseColors.WHITE,
29+
neutralQuaternaryAlt: HightContrastBaseColors.WHITE,
30+
neutralLight: HightContrastBaseColors.BLACK,
31+
neutralLighter: HightContrastBaseColors.BLACK,
32+
neutralLighterAlt: HightContrastBaseColors.BLACK,
33+
black: HightContrastBaseColors.WHITE,
34+
white: HightContrastBaseColors.BLACK,
35+
};
36+
37+
export const HightContrastSemanticColors: Partial<ISemanticColors> = {
38+
accentButtonBackground: HightContrastBaseColors.BLUE,
39+
accentButtonText: HightContrastBaseColors.BLACK,
40+
actionLink: HightContrastBaseColors.YELLOW,
41+
actionLinkHovered: HightContrastBaseColors.YELLOW,
42+
blockingBackground: HightContrastBaseColors.BLACK,
43+
blockingIcon: HightContrastBaseColors.WHITE,
44+
bodyBackground: HightContrastBaseColors.BLACK,
45+
bodyBackgroundChecked: HightContrastBaseColors.BLUE,
46+
bodyBackgroundHovered: HightContrastBaseColors.YELLOW,
47+
bodyDivider: HightContrastBaseColors.WHITE,
48+
bodyFrameBackground: HightContrastBaseColors.BLACK,
49+
bodyFrameDivider: HightContrastBaseColors.WHITE,
50+
bodyStandoutBackground: HightContrastBaseColors.BLACK,
51+
bodySubtext: HightContrastBaseColors.WHITE,
52+
bodyText: HightContrastBaseColors.WHITE,
53+
bodyTextChecked: HightContrastBaseColors.BLACK,
54+
buttonBackground: HightContrastBaseColors.BLACK,
55+
buttonBackgroundDisabled: HightContrastBaseColors.GREEN,
56+
buttonBorder: HightContrastBaseColors.WHITE,
57+
buttonBorderDisabled: HightContrastBaseColors.WHITE,
58+
buttonTextChecked: HightContrastBaseColors.BLACK,
59+
buttonTextDisabled: HightContrastBaseColors.BLACK,
60+
buttonText: HightContrastBaseColors.WHITE,
61+
buttonTextPressed: HightContrastBaseColors.BLACK,
62+
buttonTextHovered: HightContrastBaseColors.BLACK,
63+
buttonTextCheckedHovered: HightContrastBaseColors.BLACK,
64+
buttonBackgroundPressed: HightContrastBaseColors.BLUE,
65+
buttonBackgroundHovered: HightContrastBaseColors.YELLOW,
66+
buttonBackgroundChecked: HightContrastBaseColors.BLUE,
67+
buttonBackgroundCheckedHovered: HightContrastBaseColors.YELLOW,
68+
cardStandoutBackground: HightContrastBaseColors.BLACK,
69+
defaultStateBackground: HightContrastBaseColors.BLACK,
70+
disabledBodySubtext: HightContrastBaseColors.GREEN,
71+
disabledBodyText: HightContrastBaseColors.GREEN,
72+
disabledBorder: HightContrastBaseColors.GREEN,
73+
disabledSubtext: HightContrastBaseColors.GREEN,
74+
disabledBackground: HightContrastBaseColors.BLACK,
75+
disabledText: HightContrastBaseColors.GREEN,
76+
errorBackground: HightContrastBaseColors.BLACK,
77+
errorIcon: HightContrastBaseColors.WHITE,
78+
errorText: HightContrastBaseColors.WHITE,
79+
infoBackground: HightContrastBaseColors.BLACK,
80+
infoIcon: HightContrastBaseColors.WHITE,
81+
inputBackground: HightContrastBaseColors.BLACK,
82+
inputBackgroundCheckedHovered: HightContrastBaseColors.YELLOW,
83+
inputBackgroundChecked: HightContrastBaseColors.BLUE,
84+
inputBorder: HightContrastBaseColors.WHITE,
85+
inputBorderHovered: HightContrastBaseColors.YELLOW,
86+
inputFocusBorderAlt: HightContrastBaseColors.BLUE,
87+
inputForegroundChecked: HightContrastBaseColors.BLACK,
88+
inputIcon: HightContrastBaseColors.WHITE,
89+
inputIconDisabled: HightContrastBaseColors.GREEN,
90+
inputIconHovered: HightContrastBaseColors.BLACK,
91+
inputPlaceholderBackgroundChecked: HightContrastBaseColors.WHITE,
92+
inputPlaceholderText: HightContrastBaseColors.WHITE,
93+
inputText: HightContrastBaseColors.WHITE,
94+
inputTextHovered: HightContrastBaseColors.WHITE,
95+
link: HightContrastBaseColors.YELLOW,
96+
linkHovered: HightContrastBaseColors.YELLOW,
97+
listBackground: HightContrastBaseColors.BLACK,
98+
listHeaderBackgroundHovered: HightContrastBaseColors.YELLOW,
99+
listHeaderBackgroundPressed: HightContrastBaseColors.YELLOW,
100+
listItemBackgroundChecked: HightContrastBaseColors.BLUE,
101+
listItemBackgroundCheckedHovered: HightContrastBaseColors.YELLOW,
102+
listItemBackgroundHovered: HightContrastBaseColors.YELLOW,
103+
listText: HightContrastBaseColors.BLACK,
104+
menuBackground: HightContrastBaseColors.BLACK,
105+
menuItemBackgroundHovered: HightContrastBaseColors.YELLOW,
106+
menuItemBackgroundPressed: HightContrastBaseColors.YELLOW,
107+
menuDivider: HightContrastBaseColors.WHITE,
108+
menuIcon: HightContrastBaseColors.WHITE,
109+
menuHeader: HightContrastBaseColors.WHITE,
110+
menuItemText: HightContrastBaseColors.WHITE,
111+
menuItemTextHovered: HightContrastBaseColors.BLACK,
112+
messageLink: HightContrastBaseColors.YELLOW,
113+
messageLinkHovered: HightContrastBaseColors.YELLOW,
114+
messageText: HightContrastBaseColors.BLACK,
115+
primaryButtonBackground: HightContrastBaseColors.BLUE,
116+
primaryButtonBackgroundDisabled: HightContrastBaseColors.GREEN,
117+
primaryButtonBackgroundHovered: HightContrastBaseColors.YELLOW,
118+
primaryButtonBackgroundPressed: HightContrastBaseColors.BLUE,
119+
primaryButtonBorder: HightContrastBaseColors.BLACK,
120+
primaryButtonText: HightContrastBaseColors.BLACK,
121+
primaryButtonTextDisabled: HightContrastBaseColors.BLACK,
122+
primaryButtonTextHovered: HightContrastBaseColors.BLACK,
123+
primaryButtonTextPressed: HightContrastBaseColors.BLACK,
124+
severeWarningBackground: HightContrastBaseColors.YELLOW,
125+
severeWarningIcon: HightContrastBaseColors.BLACK,
126+
smallInputBorder: HightContrastBaseColors.WHITE,
127+
successBackground: HightContrastBaseColors.BLUE,
128+
successIcon: HightContrastBaseColors.BLACK,
129+
variantBorder: HightContrastBaseColors.WHITE,
130+
variantBorderHovered: HightContrastBaseColors.WHITE,
131+
warningBackground: HightContrastBaseColors.YELLOW,
132+
warningIcon: HightContrastBaseColors.BLACK
133+
};

‎src/common/fluentUITeamsThemes/HightContrastCustomizations/Styles/ChoiceGroupOption.Styles.ts

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { IChoiceGroupOptionStyleProps, IChoiceGroupOptionStyles } from 'office-ui-fabric-react/lib/ChoiceGroup';
2+
3+
export const ChoiceGroupOptionStyles = (props: IChoiceGroupOptionStyleProps): Partial<IChoiceGroupOptionStyles> => {
4+
const { disabled, theme } = props;
5+
const { semanticColors } = theme;
6+
7+
return {
8+
field: [
9+
{
10+
selectors: {
11+
':hover': [
12+
!disabled && {
13+
selectors: {
14+
'.ms-ChoiceFieldLabel': {
15+
color: semanticColors.bodyText,
16+
}
17+
}
18+
}
19+
],
20+
'.ms-ChoiceFieldLabel': {
21+
color: disabled ? semanticColors.disabledBodyText : semanticColors.bodyText,
22+
},
23+
},
24+
}
25+
],
26+
};
27+
};

0 commit comments

Comments
 (0)