@devseed-ui/theme-provider

import { Meta, Story, Canvas, ArgsTable } from '@storybook/addon-docs'; import styled from 'styled-components'; import { ThemeExplorer } from './story-theme-explorer'; import { Colors } from './story-colors'; import { Elevations } from './story-elevation'; <Meta title="Components/Theme Provider" /> # Theme Provider ``` yarn add @devseed-ui/theme-provider ``` ```js import { createUITheme, DevseedUiThemeProvider, GlobalStyles, theme, createColorPalette, unitify, rem, px, val2px, val2rem, stylizeFunction, themeVal, glsp, rgba, multiply, divide, add, subtract, min, max, antialiased, visuallyHidden, listReset, truncated, visuallyDisabled, disabled, unscrollableY, unscrollableX, media, } from '@devseed-ui/theme-provider'; ``` ## Theme values explorer <Canvas> <Story name="Theme Explorer" > <ThemeExplorer /> </Story> </Canvas> ## Colors Colors can be accessed through `themeVal` using the color name and color weight. For example: `themeVal('color.danger-400')` <Canvas> <Story name="Colors" > <Colors /> </Story> </Canvas> ## Elevation (Drop Shadow) <Canvas> <Story name="Elevations" > <Elevations /> </Story> </Canvas> ## API Documentation <Canvas> <Story name="API"> <p>List of all functions available through the theme provider</p> </Story> </Canvas> ### Theme Utilities directly related with the theme. - **DevseedUiThemeProvider** `React Component` Theme provider for the ui-library. Supports a custom theme through a `theme` prop. - **GlobalStyles** `React Component` Global styled applied by the ui-library. It is included in the `DevseedUiThemeProvider`, so this is not used often. - **createUITheme(definition)** `function` Creates a UI theme by combining the provided options with the default ones. - **theme** `object` Default ui-library theme. - **themeVal(path)** `function` Function to be used with styled-components to get a value from the theme. ```js const Msg = styled.p` color: ${themeVal('color.primary')}; `; ``` - **createColorPalette(name, baseColor)** `function` Function to create a color palette base off of the provided base color including lightened/darkened/transparent versions of that color. ### Stylizing function - **stylizeFunction(function)** `function` Utility to convert functions so that they can be used with styled-components. For example, the `tint` function provided by [Polished](https://polished.js.org/) has the following signature: ```js tint(percentage: (number | string), color: string): string ``` This means that to use a color from the theme while in a styled-component block we'd need: ```js const Msg = styled.p` color: ${({ theme }) => tint('50%', theme.color.primary)}; `; ``` By "stylizing" the function, we can use it directly and in conjunction with `themeVal` ```js const _tint = stylizeFunction(tint); const Msg = styled.p` color: ${_tint('50%', themeVal('color.primary'))}; `; ``` ### Conversions and Math Utilities to be used with styled-components to do conversions and math operations. All the functions can be used directly with styled-components and `themeVal`, for example: ```js const Msg = styled.p` padding: ${multiply(themeVal('layout.border'), 3)}; // 3px `; ``` - **unitify(unit)** `function` Return a function that appends the `unit` to the value. ```js const percent = unitify('%'); percent(10) // -> 10% ``` - **rem(value)** `function` Appends `rem` to the give value. - **px(value)** `function` Appends `rem` to the give value. - **val2px(value)** `function` Convert the given value to pixels using the base size defined in the theme (`theme.type.base.root`). - **val2rem(value)** `function` Convert the given value to rem using the base size defined in the theme (`theme.type.base.root`). - **multiply** `function` Multiplies two values keeping the unit of the first one. Eg: `2rem * 2 = 4rem | 2 * 2rem = 4` - **divide** `function` Divides two values keeping the unit of the first one. Eg: `2rem / 2 = 1rem | 2 / 2rem = 1` - **add** `function` Adds two values keeping the unit of the first one. Eg: `2rem + 2 = 4rem | 2 + 2rem = 4` - **subtract** `function` Subtracts two values keeping the unit of the first one. Eg: `4rem - 2 = 2rem | 4 - 2rem = 2` - **min** `function` Returns the minimum of two values. Units are discarded when doing the comparison, but the value is returned with a unit if both arguments has the same one or if only one has it. Eg: `10px, 15 = 10 | 4rem, 5px = 4` - **max** `function` Returns the maximun of two values. Units are discarded when doing the comparison, but the value is returned with a unit if both arguments has the same one or if only one has it. Eg: `10px, 15 = 15 | 4rem, 5px = 5` ### Global Spacing and RGBA - **glsp(...args)** `function` Almost all spacing in the library (margin, padding) is defined as multiples or fractions of the `layout.space`. This allows all the components to gracefully scale based on a single setting. This function accepts a variable number of arguments in the form of a multiplier. ```js padding: ${glsp(2, 1 / 2)}; // 2rem 0.5rem padding: ${glsp(2, 0.5)}; // 2rem 0.5rem padding: ${glsp()}; // 1rem ``` If no arguments are provided it is assumed a single value of `1`. - **rgba(color, value)** `function` Applies the given transparency value to the color. This function is the same as the `rgba` exported by the `polished` module, but modified to work with styled-components. See Stylizing function above. ```js const Msg = styled.p` color: ${rgba(themeVal('color.primary'), 0.5)}; `; ``` ### Media queries The media queries will be available through the `media` object as `Up`, `Only`, and `Down` variations of each range defined on the theme. For example, with the range (`medium: [768, 991]`): - `mediumUp` will be triggered from 768px; - `mediumOnly` will stay active between 768px and 991px; - `mediumDown` while the viewport is below or at 991px. All available options are: ``` media.xsmallOnly media.xsmallDown media.smallUp media.smallOnly media.smallDown media.mediumUp media.mediumOnly media.mediumDown media.largeUp media.largeOnly media.largeDown media.xlargeUp media.xlargeOnly ``` These can be used directly on styled-components using template literals: ```js const Msg = styled.p` color: red; ${media.mediumUp` color: blue; `} ${media.largeUp` color: green; `} `; ``` ### Helpers The helpers are to be used within a styled-component and return useful snippets of code. - **antialiased** `function` Applies anti-aliasing to font rendering, making the text more readable and pleasing to the eye. Webkit and mozilla specific. - **visuallyHidden** `function` Hides elements visually, but preserving its accessibility to screen readers or crawlers. Useful for semantic solutions. - **listReset** `function` Removes default list (`ul` and `ol`) styling. Say goodbye to default padding, margin, and bullets/numbers. - **truncated** `function` Truncates a text string and applies ellipsis. Requires a declared width value. - **disabled** `function` Applies disabled styles to an element, and disabled pointer events. - **visuallyDisabled** `function` The same behavior as `disabled`, but the pointer events remain active. This is useful when, for example, paired with a tooltip that needs the `hover` event to fire. - **unscrollableY** `function` Constrains element content to its declared height, preventing vertical scrolling. - **unscrollableX** `function` Constrains element content to its declared width, preventing horizontal scrolling. Use directly in a `styled-component`: ```js const Msg = styled.p` ${antialiased()} `; ```