Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

INSTUI-4322 Make it possible to not use global theme registry. Deprecate global theme registry. #1762

Merged
merged 2 commits into from
Nov 22, 2024
Merged

INSTUI-4322 Make it possible to not use global theme registry. Deprecate global theme registry. #1762

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7aab574
WIP(many): deprecate globalThis and allow local themes
matyasf Oct 4, 2024
133c3d7
refactor(emotion,theme-registry,ui-themes): docs, tests
matyasf Nov 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 89 additions & 65 deletions docs/guides/using-theme-overrides.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,23 +27,7 @@ type: embed

### How theming works in InstUI

The theming system in InstUI has three levels:

**The global theme**

Global themes are useful when you have multiple React Application trees and you want to set up themes and overrides on a more global level than application level theming.
This basically means you don't necessarily have to wrap each application tree with an [InstUISettingsProvider](/#InstUISettingsProvider) to use themes.
InstUI leverages the [ThemeRegistry](/#ThemeRegistry) package to achieve global theming.

```jsx
---
type: code
---
// app/init sets the global theme
import canvas from '@instructure/ui-themes'

canvas.use()
```
The theming system in InstUI has these levels:

**The application level theme**

Expand Down Expand Up @@ -95,42 +79,28 @@ const generateStyle = (componentTheme) => {
}
```

### Global theme overrides
### Application level theme overrides

In order to globally register and override themes, simply import the theme you wish to use and call `.use({ overrides })` on it:
`<InstUISettingsProvider/>` accepts full theme objects and override objects too.

```js
---
type: code
type: example
---
import ReactDOM from "react-dom"
import { canvas } from "@instructure/ui-themes"

canvas.use({
overrides: {
colors: {
primitives: {
green45: "red"
}
<InstUISettingsProvider theme={{
...canvas,
...{
typography: { fontFamily: 'monospace' }
}
}
})

ReactDOM.render(
}}>
<div>
...your application code goes here...
<Heading level="h3" margin="small small">
I should have monospace font family from the override
</Heading>
</div>
)
</InstUISettingsProvider>
```

**Note**: globally overriding themes like this means that every InstUI component will use that theme, unless they are wrapped inside an `<InstUISettingsProvider/>`.

You can see more examples [here](/#using-theme-overrides/#using-theme-overrides-examples).

### Application level theme overrides

`<InstUISettingsProvider/>` accepts full theme objects and override objects too.

#### Full themes

By nesting the `InstUISettingsProvider` you can apply different themes to some sections of you app.
Expand Down Expand Up @@ -214,27 +184,27 @@ const Example = () => {
return (
<div>
<h3>Common variables</h3>
<Flex gap="small large">
<Flex.Item size="50%">
<Flex gap="small">
<Flex.Item size="45%">
<TextInput renderLabel="ic-brand-primary" value={icBrandPrimary} onChange={(e, v) => setIcBrandPrimary(v)}
messages={[{text:'used for border/background/shadow/focus colors in many places',type:'hint'}]} />
messages={[{text:'used for border/background/focus/shadow/.. colors in many places',type:'hint'}]} />
</Flex.Item>
<Flex.Item size="50%">
<Flex.Item size="45%">
<TextInput renderLabel="ic-brand-font-color-dark" value={icBrandFontColorDark} onChange={(e, v) => setIcBrandFontColorDark(v)}
messages={[{text:'used in lots of places for text color',type:'hint'}]} />
</Flex.Item>
</Flex>

<h3><code>Button</code> branding</h3>
<Flex gap="small large">
<Flex.Item size="50%">
<Flex gap="small">
<Flex.Item size="45%">
<TextInput renderLabel="ic-brand-button--primary-bgd" value={icBrandButtonPrimaryBgd} onChange={(e, v) => setIcBrandButtonPrimaryBgd(v)}
messages={[{text:"Used by 'primary' color buttons for background",type:'hint'}]} />
<br/>
<TextInput renderLabel="ic-brand-button--primary-text" value={icBrandButtonPrimaryText} onChange={(e, v) => setIcBrandButtonPrimaryText(v)}
messages={[{text:"Used by 'primary' color buttons for text color",type:'hint'}]} />
</Flex.Item>
<Flex.Item size="50%">
<Flex.Item size="45%">
<TextInput renderLabel="ic-brand-button--secondary-bgd" value={icBrandButtonSecondaryBgd} onChange={(e, v) => setIcBrandButtonSecondaryBgd(v)}
messages={[{text:'Unused in InstUI',type:'hint'}]} />
<br/>
Expand All @@ -260,13 +230,17 @@ const Example = () => {
'ic-brand-global-nav-menu-item__text-color--active': icBrandGlobalNavMenuItemTextColorActive
}}}>
<hr style={{width:'100%'}}/>
<Flex gap="small large">
<Flex.Item size="50%">
<Button color="primary">I'm a 'primary' color button</Button>
<Flex gap="large">
<Flex.Item size="45%">
<Badge count={15} countUntil={100} margin="0 medium 0 0">
<Button color="primary">I'm a 'primary' color button</Button>
</Badge>
<TextInput renderLabel="TextInput" placeholder="ic-brand-primary sets focus color"/>
</Flex.Item>
<Flex.Item size="50%">
<Button color="secondary">I'm a 'secondary' color button</Button>
<Flex.Item size="45%">
<Badge count={15} countUntil={100} margin="0 medium 0 0">
<Button color="secondary">I'm a 'secondary' color button</Button>
</Badge>
<TextArea label="TextArea" placeholder="ic-brand-primary sets focus color"/>
</Flex.Item>
</Flex>
Expand All @@ -280,18 +254,18 @@ const Example = () => {

<hr style={{width:'100%'}}/>
<h3>Link colors used by <code>Link</code> and <code>Billboard</code>:</h3>
<Flex gap="small large">
<Flex.Item size="50%">
<Flex gap="small">
<Flex.Item size="45%">
<TextInput renderLabel="ic-link-color" value={icLinkColor} onChange={(e, v) => setIcLinkColor(v)}
messages={[{text:'Used for non-inverse Link and clickable Billboard',type:'hint'}]} />
</Flex.Item>
<Flex.Item size="50%">
<Flex.Item size="45%">
<TextInput renderLabel="ic-link-decoration" value={icLinkDecoration} onChange={(e, v) => setIcLinkDecoration(v)}
messages={[{text:'Unused in InstUI',type:'hint'}]}/>
</Flex.Item>
</Flex>
<hr style={{width:'100%'}}/>
<Flex gap="small large">
<Flex gap="small">
<Flex.Item size="50%">
<Link href="https://instructure.github.io/instructure-ui/">normal link</Link>
</Flex.Item>
Expand All @@ -301,16 +275,16 @@ const Example = () => {
</View>
</Flex.Item>
</Flex>
<Flex gap="small large">
<Flex.Item size="50%">
<Flex gap="small">
<Flex.Item size="40%">
<Billboard
margin="small"
message="Billboard with link"
href="http://instructure.com"
hero={(size) => <IconGradebookLine size={size} />}
/>
</Flex.Item>
<Flex.Item size="50%">
<Flex.Item size="40%">
<Billboard
margin="small"
message="Billboard without link"
Expand All @@ -321,13 +295,13 @@ const Example = () => {

<hr style={{width:'100%'}}/>
<h3><code>SideNavBar</code> branding</h3>
<Flex gap="small large">
<Flex.Item size="50%">
<Flex gap="large small">
<Flex.Item size="45%">
<TextInput renderLabel="ic-brand-global-nav-bgd" value={icBrandGlobalNavBgd} onChange={(e, v) => setIcBrandGlobalNavBgd(v)}/>
<TextInput renderLabel="ic-global-nav-link-hover" value={icGlobalNavLinkHover} onChange={(e, v) => setIcGlobalNavLinkHover(v)}/>
<TextInput renderLabel="ic-brand-global-nav-ic-icon-svg-fill" value={icBrandGlobalNavIcIconSvgFill} onChange={(e, v) => setIcBrandGlobalNavIcIconSvgFill(v)}/>
</Flex.Item>
<Flex.Item size="50%">
<Flex.Item size="45%">
<TextInput renderLabel="ic-brand-global-nav-menu-item__text-color" value={icBrandGlobalNavMenuItemTextColor} onChange={(e, v) => setIcBrandGlobalNavMenuItemTextColor(v)}/>
<TextInput renderLabel="ic-brand-global-nav-menu-item__text-color--active" value={icBrandGlobalNavMenuItemTextColorActive} onChange={(e, v) => setIcBrandGlobalNavMenuItemTextColorActive(v)}/>
<TextInput renderLabel="ic-brand-global-nav-ic-icon-svg-fill--active" value={icBrandGlobalNavIcIconSvgFillActive} onChange={(e, v) => setIcBrandGlobalNavIcIconSvgFillActive(v)}/>
Expand Down Expand Up @@ -386,3 +360,53 @@ const Example = () => {

render(<Example/>)
```

### (DEPRECATED) Global (window-level) theming

**The global theme**

> This feature is deprecated because it needs to use the [global object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) that pierces application borders, so it causes issues with running multiple versions of InstUI in a single page.

Global themes are useful when you have multiple React Application trees, and you want to set up themes and overrides on a more global level than application level theming.
This basically means you don't necessarily have to wrap each application tree with an [InstUISettingsProvider](/#InstUISettingsProvider) to use themes.
InstUI leverages the [ThemeRegistry](/#ThemeRegistry) package to achieve global theming.

```jsx
---
type: code
---
// app/init sets the global theme
import canvas from '@instructure/ui-themes'

canvas.use()
```

### (DEPRECATED) Global theme overrides

In order to globally register and override themes, simply import the theme you wish to use and call `.use({ overrides })` on it:

```js
---
type: code
---
import ReactDOM from "react-dom"
import { canvas } from "@instructure/ui-themes"

canvas.use({
overrides: {
colors: {
primitives: {
green45: "red"
}
}
}
})

ReactDOM.render(
<div>
...your application code goes here...
</div>
)
```

**Note**: globally overriding themes like this means that every InstUI component will use that theme, unless they are wrapped inside an `<InstUISettingsProvider/>`.
7 changes: 6 additions & 1 deletion packages/__docs__/components.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,4 +130,9 @@ export { Drilldown } from '@instructure/ui-drilldown'
export { SourceCodeEditor } from '@instructure/ui-source-code-editor'
export { TopNavBar } from '@instructure/ui-top-nav-bar'
export { TruncateList } from '@instructure/ui-truncate-list'
export { canvas, canvasHighContrast, instructure } from '@instructure/ui-themes'
export {
canvas,
canvasHighContrast,
canvasThemeLocal,
canvasHighContrastThemeLocal
} from '@instructure/ui-themes'
2 changes: 1 addition & 1 deletion packages/__docs__/src/Theme/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,7 +279,7 @@ class Theme extends Component<ThemeProps> {
id={`${themeKey}ApplicationUsage`}
content={`
### Usage (before mounting your application)
##### Global theming
##### (DEPRECATED) Global theming
${'```javascript\n \
---\n \
type: code\n \
Expand Down
Loading
Loading