New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
@devseed-ui/theme-provider
Advanced tools
@devseed-ui/theme-provider - npm Package Compare versions
Comparing version 4.0.2 to 4.1.0
| { | ||
| "name": "@devseed-ui/theme-provider", | ||
| "version": "4.0.2", | ||
| "version": "4.1.0", | ||
| "description": "devseed UI Kit Theme", | ||
@@ -33,3 +33,3 @@ "main": "dist/index.cjs.js", | ||
| }, | ||
| "gitHead": "cf6177d43da930ba89fc096854cdbf48e9f8ce48" | ||
| "gitHead": "174914d3dabced4713b52f8ffd1e4a47c37b7703" | ||
| } |
283
README.md
| # @devseed-ui/theme-provider | ||
| ```code | ||
| import { | ||
| // Theme | ||
| DevseedUiThemeProvider, | ||
| GlobalStyles, | ||
| createUITheme, | ||
| theme, | ||
| themeVal, | ||
| createColorPalette, | ||
| // Stylizing function | ||
| stylizeFunction, | ||
| // Conversions and math | ||
| unitify, | ||
| rem, | ||
| px, | ||
| val2px, | ||
| val2rem, | ||
| multiply, | ||
| divide, | ||
| add, | ||
| subtract, | ||
| min, | ||
| max, | ||
| // Global spacing and RGBA | ||
| glsp, | ||
| rgba, | ||
| // Media queries | ||
| media, | ||
| // Style helpers | ||
| antialiased, | ||
| visuallyHidden, | ||
| listReset, | ||
| truncated, | ||
| visuallyDisabled, | ||
| disabled, | ||
| unscrollableY, | ||
| unscrollableX | ||
| } from '@devseed-ui/theme-provider'; | ||
| ``` | ||
| See the [API reference](#api-documentation) for a description of each export. | ||
| # Devseed-ui Theme Provider | ||
| ## How theming works with the ui-library | ||
| The components of the devseed-ui library require settings to be defined through a theme using specific variables. | ||
| The `theme-provider` contains the base provider with the ui-library's default theme. This can be used directly, or overridden by the user. | ||
| ```code | ||
| import { DevseedUiThemeProvider } from '@devseed-ui/theme-provider'; | ||
| ``` | ||
| The `DevseedUiThemeProvider` should wrap the whole application so that all components can get the correct variables from the theme. | ||
| This will apply the default ui-library theme and some global styles to normalize presentation across browsers. | ||
| ```code | ||
| ... | ||
| render ( | ||
| <DevseedUiThemeProvider> | ||
| {components...} | ||
| <DevseedUiThemeProvider | ||
| ) | ||
| ``` | ||
| It is also possible to provide a custom theme to `DevseedUiThemeProvider` using the `theme` prop. | ||
| **It is important that the custom theme contains a value for all variables in the theme.** | ||
| ```code | ||
| const myCustomTheme = { | ||
| ... | ||
| }; | ||
| ... | ||
| render ( | ||
| <DevseedUiThemeProvider theme={myCustomTheme}> | ||
| {components...} | ||
| <DevseedUiThemeProvider | ||
| ) | ||
| ``` | ||
| The best way to provide a new theme is to use the `createUITheme` helper and override the base theme variables, while also being able to add new variables. | ||
| This helper will ensure that defaults are set when no custom values are provided. Check (./src/theme.d.ts)[theme.d.ts] for a list of all theme properties. | ||
| ```code | ||
| const myCustomTheme = createUITheme({ | ||
| color: { | ||
| base: '#F00', | ||
| // This is a custom color. | ||
| infographicColor: '#FF0' | ||
| } | ||
| }); | ||
| ... | ||
| render ( | ||
| <DevseedUiThemeProvider theme={myCustomTheme}> | ||
| {components...} | ||
| <DevseedUiThemeProvider | ||
| ) | ||
| ``` | ||
| ## Theme | ||
| Check [theme.d.ts](./src/theme.d.ts) for the default ui-library theme values. | ||
| # API Documentation | ||
| ### Theme | ||
| Utilities directly related with the theme. | ||
| - `DevseedUiThemeProvider` [React Component] | ||
| - Theme provider for the ui-library. Supports a custom theme through a `theme` prop. See [How theming works with the ui-library](#how-theming-works-with-the-ui-library). | ||
| - `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. | ||
| ```code | ||
| 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: | ||
| ```code | ||
| 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: | ||
| ```code | ||
| 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` | ||
| ```code | ||
| 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: | ||
| ```code | ||
| const Msg = styled.p` | ||
| padding: ${multiply(themeVal('layout.border'), 3)}; // 3px | ||
| `; | ||
| ``` | ||
| - `unitify(unit)` [function] | ||
| - Return a function that appends the `unit` to the value. | ||
| ``` | ||
| 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. | ||
| ```code | ||
| 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](#stylizing-function). | ||
| ```code | ||
| 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: | ||
| ```code | ||
| 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: | ||
| ```code | ||
| const Msg = styled.p` | ||
| ${antialiased()} | ||
| `; | ||
| ``` | ||
| This module has several utilities amongst which is the `DevseedUiThemeProvider` which functions like styled-component's `<ThemeProvider>` and provides a theme to the provider's child components via the context API. |
@@ -1,2 +0,2 @@ | ||
| type StyledComponentsCSS = () => any; | ||
| import { FlattenSimpleInterpolation } from "styled-components"; | ||
@@ -8,3 +8,3 @@ declare module '@devseed-ui/theme-provider' { | ||
| */ | ||
| function antialiased(): StyledComponentsCSS; | ||
| function antialiased(): FlattenSimpleInterpolation; | ||
@@ -15,3 +15,3 @@ /** | ||
| */ | ||
| function visuallyHidden(): StyledComponentsCSS; | ||
| function visuallyHidden(): FlattenSimpleInterpolation; | ||
@@ -22,3 +22,3 @@ /** | ||
| */ | ||
| function listReset(): StyledComponentsCSS; | ||
| function listReset(): FlattenSimpleInterpolation; | ||
@@ -29,3 +29,3 @@ /** | ||
| */ | ||
| function truncated(): StyledComponentsCSS; | ||
| function truncated(): FlattenSimpleInterpolation; | ||
@@ -35,3 +35,3 @@ /** | ||
| */ | ||
| function visuallyDisabled(): StyledComponentsCSS; | ||
| function visuallyDisabled(): FlattenSimpleInterpolation; | ||
@@ -43,3 +43,3 @@ /** | ||
| */ | ||
| function disabled(): StyledComponentsCSS; | ||
| function disabled(): FlattenSimpleInterpolation; | ||
@@ -50,3 +50,3 @@ /** | ||
| */ | ||
| function unscrollableY(): StyledComponentsCSS; | ||
| function unscrollableY(): FlattenSimpleInterpolation; | ||
@@ -57,3 +57,3 @@ /** | ||
| */ | ||
| function unscrollableX(): StyledComponentsCSS; | ||
| function unscrollableX(): FlattenSimpleInterpolation; | ||
| } |
| declare module '@devseed-ui/theme-provider' { | ||
| type MathFnTypeOut = number | string; | ||
| type MathFnTypeIn = MathFnTypeOut | ThemeValReturn; | ||
| /** | ||
@@ -11,3 +15,3 @@ * Creates a math function to add values. It takes into account | ||
| */ | ||
| function add<T extends number | string>(a: T, b: number | string): T; | ||
| function add(a: MathFnTypeIn, b: MathFnTypeIn): MathFnTypeOut; | ||
@@ -23,3 +27,3 @@ /** | ||
| */ | ||
| function subtract<T extends number | string>(a: T, b: number | string): T; | ||
| function subtract(a: MathFnTypeIn, b: MathFnTypeIn): MathFnTypeOut; | ||
@@ -35,3 +39,3 @@ /** | ||
| */ | ||
| function divide<T extends number | string>(a: T, b: number | string): T; | ||
| function divide(a: MathFnTypeIn, b: MathFnTypeIn): MathFnTypeOut; | ||
@@ -47,3 +51,3 @@ /** | ||
| */ | ||
| function multiply<T extends number | string>(a: T, b: number | string): T; | ||
| function multiply(a: MathFnTypeIn, b: MathFnTypeIn): MathFnTypeOut; | ||
@@ -64,3 +68,3 @@ /** | ||
| */ | ||
| function min<T extends number | string>(a: T, b: number | string): T; | ||
| function min(a: MathFnTypeIn, b: MathFnTypeIn): MathFnTypeOut; | ||
@@ -81,3 +85,3 @@ /** | ||
| */ | ||
| function max<T extends number | string>(a: T, b: number | string): T; | ||
| function max(a: MathFnTypeIn, b: MathFnTypeIn): MathFnTypeOut; | ||
| } |
@@ -1,2 +0,2 @@ | ||
| type StyledComponentsCSS = () => any; | ||
| import { DefaultTheme, ThemedCssFunction } from "styled-components"; | ||
@@ -9,14 +9,14 @@ declare module '@devseed-ui/theme-provider' { | ||
| const media: { | ||
| xsmallDown: StyledComponentsCSS; | ||
| smallUp: StyledComponentsCSS; | ||
| smallOnly: StyledComponentsCSS; | ||
| smallDown: StyledComponentsCSS; | ||
| mediumUp: StyledComponentsCSS; | ||
| mediumOnly: StyledComponentsCSS; | ||
| mediumDown: StyledComponentsCSS; | ||
| largeUp: StyledComponentsCSS; | ||
| largeOnly: StyledComponentsCSS; | ||
| largeDown: StyledComponentsCSS; | ||
| xlargeUp: StyledComponentsCSS; | ||
| xsmallDown: ThemedCssFunction<DefaultTheme>; | ||
| smallUp: ThemedCssFunction<DefaultTheme>; | ||
| smallOnly: ThemedCssFunction<DefaultTheme>; | ||
| smallDown: ThemedCssFunction<DefaultTheme>; | ||
| mediumUp: ThemedCssFunction<DefaultTheme>; | ||
| mediumOnly: ThemedCssFunction<DefaultTheme>; | ||
| mediumDown: ThemedCssFunction<DefaultTheme>; | ||
| largeUp: ThemedCssFunction<DefaultTheme>; | ||
| largeOnly: ThemedCssFunction<DefaultTheme>; | ||
| largeDown: ThemedCssFunction<DefaultTheme>; | ||
| xlargeUp: ThemedCssFunction<DefaultTheme>; | ||
| } | ||
| } |
@@ -5,5 +5,4 @@ import './color-palette'; | ||
| import './math'; | ||
| import { DefaultTheme, FlattenSimpleInterpolation } from 'styled-components'; | ||
| type StyledComponentsCSS = () => any; | ||
| declare module '@devseed-ui/theme-provider' { | ||
@@ -201,2 +200,6 @@ type ThemeValPath = | ||
| export type ThemeValReturn = (props: { | ||
| theme: DefaultTheme; | ||
| }) => string | number; | ||
| /** | ||
@@ -208,5 +211,3 @@ * Returns a function to be used with styled-components and gets a value from | ||
| */ | ||
| function themeVal( | ||
| path: ThemeValPath, | ||
| ): (props: { theme: { [key: string]: string | number } }) => string | number; | ||
| function themeVal(path: ThemeValPath): ThemeValReturn; | ||
@@ -228,4 +229,4 @@ /** | ||
| function stylizeFunction( | ||
| fn: (...args: Array<any>) => any, | ||
| ): StyledComponentsCSS; | ||
| fn: (...args: Array<any>) => any | ||
| ): FlattenSimpleInterpolation; | ||
@@ -238,3 +239,3 @@ /** | ||
| */ | ||
| function glsp(...multiplier: number[]): StyledComponentsCSS | string; | ||
| function glsp(...multiplier: number[]): FlattenSimpleInterpolation | string; | ||
@@ -241,0 +242,0 @@ /** |
Sorry, the diff of this file is not supported yet
No alert changes
Improved metrics
- Total package byte prevSize
- increased by2.38%
760128
- Number of package files
- increased by3.57%
29
- Lines of code
- increased by9.79%
8017
Worsened metrics
- Number of lines in readme file
- decreased by-98.95%
3
No dependency changes