diff --git a/packages/blade/.storybook/react/preview.js b/packages/blade/.storybook/react/preview.js index 2e0f1469cd5..58ff3c8df2c 100644 --- a/packages/blade/.storybook/react/preview.js +++ b/packages/blade/.storybook/react/preview.js @@ -34,6 +34,7 @@ export const parameters = { 'Motion', 'CSS Variables', ], + 'Utils', 'Components', 'Recipes', ], diff --git a/packages/blade/docs/utils/useTheme.stories.mdx b/packages/blade/docs/utils/useTheme.stories.mdx new file mode 100644 index 00000000000..f13ba4d27db --- /dev/null +++ b/packages/blade/docs/utils/useTheme.stories.mdx @@ -0,0 +1,108 @@ +import { Meta } from '@storybook/addon-docs'; + + + +## useTheme + +- [Overview](#overview) +- [Usage](#usage) +- [Types](#types) + - [`Theme`](#theme) + - [`ColorScheme`](#colorscheme) + - [`Platform`](#platform) + - [`ColorSchemeInput`](#colorschemeinput) + +### Overview + +`useTheme` is a custom React hook provided by the `@razorpay/blade/utils`  that allows you to access the current theme and color scheme of your application. + +The `useTheme` hook returns a `ThemeContext` object that contains the following properties: + +| Property | Type | Description | +| ---------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| `theme` | [`Theme`](#theme) | The current theme object, which contains the values for various design tokens such as colors, typography, and spacing. | +| `colorScheme` | [`ColorScheme`](#colorscheme) | The current color scheme of the application, which can be either 'light' or 'dark'. | +| `platform` | [`Platform`](#platform) | The current platform of the application, which can be either 'onDesktop' or 'onMobile'. | +| `setColorScheme` | `(colorScheme: `[`ColorSchemeInput`](#colorschemeinput)`) => void` | A function that allows you to set the color scheme of the application. | + +### Usage + +To use the `useTheme` hook, you must first wrap your application with a `BladeProvider` component, which provides the theme context to all child components. Here's an example of how to use the `useTheme` hook in a React component: + +```tsx +import React from 'react'; +import { useTheme, Heading, Text, Button } from '@razorpay/blade/utis'; + +const MyComponent = () => { + const { theme, colorScheme, platform, setColorScheme } = useTheme(); + + return ( + <> + Hello, world! + The current color scheme is: {colorScheme} + The current platform is: {platform} + + + ); +}; + +export default MyComponent; +``` + +### Types + +#### `Theme` + +```tsx +type Theme = { + name: 'paymentTheme' | 'bankingTheme'; + border: Border; + breakpoints: Breakpoints; + colors: Colors; + spacing: Spacing; + motion: Motion; + elevation: Elevation; + typography: Typography; +}; +``` + +To further explore the tokens in Theme, you can navigate to their respective documentations: + +- [Border](?path=/story/tokens-border--page) +- [Breakpoints](?path=/story/tokens-breakpoints--page) +- [Colors](?path=/story/tokens-colors--page) +- [Spacing](?path=/story/tokens-spacing--page) +- [Motion](?path=/story/tokens-motion--page) +- [Elevation](?path=/story/tokens-elevation--page) +- [Typography](?path=/story/tokens-typography--page) + +#### `ColorScheme` + +The current color scheme of the application. Can be either `'dark'` or `'light'`. +If color scheme is set to 'system' using `setColorScheme`, the colorScheme property will return `'dark'` or `'light'` based on the user's system preferences. + +```tsx +type ColorScheme = 'dark' | 'light'; +``` + +#### `Platform` + +The current platform of the application. Can be either `'onDesktop'` or `'onMobile'`. +Platform will be set to `'onDesktop'` or `'onMobile'` based on the [breakpoints](?path=/story/tokens-breakpoints--page&globals=measureEnabled:false) defined in the theme. + +> Note: Platform will always be `'onMobile'` for React Native + +```tsx +type Platform = 'onDesktop' | 'onMobile'; +``` + +#### `ColorSchemeInput` + +You can set the color scheme of your application to either `'dark'`, `'light'` or `'system'` using `setColorScheme`. +Selecting `system` will set the color scheme of your application based on the user's system preferences. + +```tsx +type ColorSchemeInput = 'dark' | 'light' | 'system'; +``` diff --git a/packages/blade/src/tokens/theme/overrideTheme.stories.tsx b/packages/blade/src/tokens/theme/overrideTheme.stories.tsx index d39be847656..43bdc5a105a 100644 --- a/packages/blade/src/tokens/theme/overrideTheme.stories.tsx +++ b/packages/blade/src/tokens/theme/overrideTheme.stories.tsx @@ -55,7 +55,7 @@ const Page = (): ReactElement => { }; export default { - title: 'Utilities/overrideTheme', + title: 'Utils/overrideTheme', args: { hue: 259, }, diff --git a/packages/blade/src/utils/index.ts b/packages/blade/src/utils/index.ts index 2997e7970d0..1acb4a01f1e 100644 --- a/packages/blade/src/utils/index.ts +++ b/packages/blade/src/utils/index.ts @@ -15,3 +15,5 @@ export * from './makeSize'; // https://github.com/razorpay/blade/pull/1193#issuecomment-1609122359 export * from './toTitleCase'; export * from './usePrevious'; + +export { default as useTheme, ThemeContext } from '~components/BladeProvider/useTheme';