@workday/canvas-kit-react 15.0.0-alpha.1303-next.0 → 15.0.0

package/common/lib/theming/README.md

@@ -1,7 +1,10 @@
 # Canvas Kit Theming
 
-Canvas Kit Common contains wrappers and types to enabling theming of Canvas components as well as
-utilities that are used across components.
+> **Deprecation Notice:** The `theme` prop on `CanvasProvider` and all associated theming utilities
+> (`useTheme`, `getTheme`, `styled`, `defaultCanvasTheme`, `ContentDirection`, etc.) are deprecated.
+> Please use CSS variables from `@workday/canvas-tokens-web` for theming. For the full theming
+> guide, see our
+> [Theming Documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs).
 
 ## Installation
 
@@ -9,330 +12,103 @@ utilities that are used across components.
 yarn add @workday/canvas-kit-react/common
 ```
 
-## Usage
+## Recommended Approach: CSS Variables
 
-Wrap all of your Canvas components with the `CanvasProvider` higher order component. Usually this
-would go in the highest level component of your application. This includes an
-[`InputProvider`](../../README.md#input-provider) and includes all global configuration needed for
-our Canvas Components.
+Canvas Kit v14+ promotes using CSS variables for theming. Import CSS variable files and override
+values in your root CSS:
 
-```tsx
-import * as React from 'react';
-import {CanvasProvider} from '@workday/canvas-kit-react/common';
-
-<CanvasProvider>{/* All your components containing any Canvas components */}</CanvasProvider>;
-```
-
-## Component Props
-
-### Required
-
-> None
-
-### Optional
+```css
+/* index.css */
+@import '@workday/canvas-tokens-web/css/base/_variables.css';
+@import '@workday/canvas-tokens-web/css/system/_variables.css';
+@import '@workday/canvas-tokens-web/css/brand/_variables.css';
+@import '@workday/canvas-tokens-web/css/component/_variables.css';
 
-#### `theme: PartialEmotionCanvasTheme`
-
-> The theme to be used throughout the children of the `CanvasProvider` component.
-
-Default: `{ canvas: defaultCanvasTheme }`
-
-## Theme Object
-
-The Canvas theme is based on the following object:
-
-```ts
-export const defaultCanvasTheme: CanvasTheme = {
-  palette: {
-    primary: {
-      lightest: colors.blueberry100,
-      light: colors.blueberry200,
-      main: colors.blueberry400,
-      dark: colors.blueberry500,
-      darkest: colors.blueberry600,
-      contrast: colors.frenchVanilla100,
-    },
-    caution: {
-      lightest: colors.cantaloupe100,
-      light: colors.cantaloupe300,
-      main: colors.cantaloupe400,
-      dark: colors.cantaloupe500,
-      darkest: colors.cantaloupe600,
-      contrast: colors.frenchVanilla100,
-    },
-    error: {
-      lightest: colors.cinnamon100,
-      light: colors.cinnamon300,
-      main: colors.cinnamon500,
-      dark: colors.cinnamon600,
-      darkest: '#80160E',
-      contrast: colors.frenchVanilla100,
-    },
-    success: {
-      lightest: colors.greenApple100,
-      light: colors.greenApple300,
-      main: colors.greenApple600,
-      dark: '',
-      darkest: '',
-      contrast: colors.frenchVanilla100,
-    },
-    neutral: {
-      lightest: colors.soap200,
-      light: colors.soap300,
-      main: colors.soap600,
-      dark: colors.licorice300,
-      darkest: colors.licorice400,
-      contrast: colors.frenchVanilla100,
-    },
-    common: {
-      focusOutline: colors.blueberry400,
-    },
-  },
-  breakpoints: {
-    values: {
-      zero: 0,
-      s: 320,
-      m: 768,
-      l: 1024,
-      xl: 1440,
-    },
-    up,
-    down,
-    between,
-    only,
-  },
-  direction: ContentDirection.LTR,
-};
+:root {
+  /* Override brand primary colors */
+  --cnvs-brand-primary-base: var(--cnvs-base-palette-magenta-600);
+  --cnvs-brand-primary-light: var(--cnvs-base-palette-magenta-200);
+  --cnvs-brand-primary-dark: var(--cnvs-base-palette-magenta-700);
+}
 ```
 
-Any changes will be reflected across all supported components. You are also able to consume for your
-own use cases.
-
-## Custom Theme
-
-The `CanvasProvider` accepts a full or partial theme object to give a branded look or a different
-direction to the component library.
-
-> Note: Our theme is namespaced under the `canvas` key within the Emotion `ThemeContext`.
-
-For a consistent theming experience, provide a value for each property in the theme object. Use our
-CSS variables.
-
-Example:
+Or use `createStyles` to generate themed class names:
 
 ```tsx
-import {CanvasProvider, EmotionCanvasTheme} from '@workday/canvas-kit-react/common';
-import {brand} from '@workday/canvas-tokens-web';
-
-const theme: EmotionCanvasTheme = {
-  canvas: {
-    palette: {
-      primary: {
-        lightest: base.magenta25,
-        lighter: base.magenta50,
-        light: base.magenta200,
-        main: base.magenta600,
-        dark: base.magenta700,
-        darkest: base.magenta800,
-        contrast: base.neutral0,
-      },
-    },
-  },
-};
-
-<CanvasProvider theme={theme}>{/* Your app with Canvas components */}</CanvasProvider>;
-```
-
-### Bidirectionality
-
-We strongly encourage the use of
-[CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties)
-for styling. All previous bidirectionality in the Canvas theme have been deprecated.
-
-### Nesting CanvasProvider components
-
-It is possible to set a theme for a specific component or set of components within your React tree.
-This is generally discouraged for consistency reasons, but may be required in some contexts (a green
-`Switch` component for example, or changing the direction of a set of components). To do this, you
-can nest CanvasProvider components with a different theme.
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {base, brand} from '@workday/canvas-tokens-web';
 
-```tsx
-import * as React from 'react';
-import {
-  CanvasProvider,
-  EmotionCanvasTheme,
-  PartialEmotionCanvasTheme,
-  ContentDirection,
-} from '@workday/canvas-kit-react/common';
-import {Switch} from '@workday/canvas-kit-react/switch';
-
-const rtlTheme: EmotionCanvasTheme = {
-  canvas: {
-    direction: ContentDirection.RTL,
-  },
-};
-
-const theme: PartialEmotionCanvasTheme = {
-  canvas: {
-    palette: {
-      primary: {
-        main: colors.greenApple400,
-      },
-    },
-    direction: ContentDirection.LTR,
-  },
-};
+const themedBrand = createStyles({
+  [brand.primary.base]: base.legacy.magenta600,
+  [brand.primary.dark]: base.legacy.magenta700,
+});
 
-<CanvasProvider theme={rtlTheme}>
-  <CanvasProvider theme={theme}>
-    <Switch checked={true} />
-    {/* Content that should be LTR */}
-  </CanvasProvider>
+<CanvasProvider className={themedBrand}>
+  <App />
 </CanvasProvider>;
 ```
 
-### Context Alternative
+## Bidirectionality (RTL Support)
 
-If, for whatever reason, you're not able to use React Contexts, we offer an alternative. A good
-example of this is an app with many small React trees.
+### Setting RTL Direction
 
-Simply set your theme on the window object like so:
+Use the native HTML `dir` attribute to set the text direction. The `CanvasProvider` accepts a `dir`
+prop:
 
 ```tsx
-const theme: PartialEmotionCanvasTheme = {
-  canvas: {
-    palette: {
-      primary: {
-        main: colors.greenApple400,
-      },
-    },
-  },
-};
-
-window.workday.canvas.theme = theme;
-```
-
-Note if any of the window object hasn't been defined, you will need to change your assignment. For
-example:
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
 
-```tsx
-window.workday = {
-  canvas: {
-    theme: theme;
-  }
-}
+<CanvasProvider dir="rtl">
+  <App />
+</CanvasProvider>;
 ```
 
-If the theme is not available via a context, Canvas Kit components will attempt to pull it from this
-variable before falling back to the default theme.
+### CSS Logical Properties
 
-## Accessing the theme value
-
-Canvas Kit provides two functions to access the current theme, `getTheme` and `useTheme`. If you
-need to access the theme within a function component, use the hook, `useTheme`. If you need to
-access the theme within a `styled` component, a class component, or outside a component, use
-`getTheme`. The main difference is `useTheme` is intended to work within the `CanvasProvider` and
-will check the `ThemeContext` for the theme first. Both functions check the window for the theme and
-fall back to the default theme is nothing is found. Both functions will return a full theme object
-in this shape:
-
-**Return value**
+Use
+[CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties)
+for styling. These automatically adapt to the text direction:
 
-```tsx
-{
-  canvas: {
-    palette: {
-      // ...
-    },
-    breakpoints: {
-      // ...
-    },
-    direction: ContentDirection.LTR,
-  },
-  // other themes can be placed here
+```css
+/* Use CSS logical properties */
+.my-component {
+  margin-inline-start: 1rem; /* Instead of margin-left */
+  padding-inline-end: 1rem; /* Instead of padding-right */
 }
 ```
 
-### getTheme
-
-`getTheme` is a function that returns the full theme object with the Canvas Kit theme under the
-`canvas` key. It should be used with `styled` components, class components, or outside components.
+### Conditional RTL Styles
 
-Below is an example of how to use `getTheme` to build responsive media query styles with the
-breakpoint functions provided in the theme.
+For styles that need to change based on direction, use the
+[`:dir()` pseudo-class selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir):
 
-```tsx
-import {getTheme} from '@workday/canvas-kit-react/common';
-
-const theme = getTheme();
-const {up, down} = theme.canvas.breakpoints;
-const small = down('m'); // Returns '@media (max-width: 768px)'
-const medium = up('m'); // Returns '@media (min-width: 768px)'
-const styles = {
-  [small]: {
-    margin: space.m,
-  },
-  [medium]: {
-    margin: space.l,
-  },
-};
-```
-
-### useTheme
-
-`useTheme` is hook to get the full theme object. It should be used only with functional compoents
-wrapped in ContextProvider. Function returns a theme object with the Canvas Kit theme under the
-canvas key.
-
-`useTheme` should be used only inside functional component otherwise it will show a warning if the
-theme context value has not been found. In that case you will need to use `getTheme`.
-
-Below is an example showing how to use `useTheme` in a function component to set `Subtext`'s color
-to the error color provided by the theme.
-
-```tsx
-export const ErrorMessage = () => {
-  const theme = useTheme();
-  return (
-    <Subtext size="large" color={theme.canvas.palette.error.main}>
-  )
+```css
+/* Use :dir() for RTL-specific styles */
+.my-component:dir(rtl) {
+  /* RTL-specific styles */
 }
 ```
 
-### Overwriting the theme
-
-You can also use both functions to overwrite the theme object by providing a partial or full theme
-object to overwrite the current theme. In the example below, we're setting a custom content
-direction, which can be passed to either `useTheme` or `getTheme`. These functions will properly
-merge your the partial theme with the default Canvas theme and return a complete theme object.
-
 ```tsx
-import {ContentDirection, useTheme, getTheme} from '@workday/canvas-kit-react/common';
+import {createStyles} from '@workday/canvas-kit-styling';
 
-const customTheme = {
-  canvas: {
-    // set the content direction to right-to-left
-    direction: ContentDirection.RTL,
+const styles = createStyles({
+  ':dir(rtl)': {
+    svg: {
+      transform: 'rotate(180deg)',
+    },
   },
-};
-
-// Overwriting the theme with useTheme
-const customTheme = useTheme(customTheme);
-
-// Overwriting the theme with getTheme
-const customTheme = getTheme(customTheme);
+});
 ```
 
 ## Breakpoints
 
-Breakpoints are used by media queries to conditionally apply or modify styles based on the viewport
-width. This allows the UI to be responsive to various screen sizes.
+Breakpoints are used by media queries to conditionally apply or modify styles based on viewport
+width.
 
 ### Values
 
-The canvas theme object provides five breakpoint values that correspond to the min-widths of our
-standard screen sizes.
-
 | Name   | Size (px) |
 | ------ | --------- |
 | `zero` | 0         |
@@ -341,186 +117,70 @@ standard screen sizes.
 | `l`    | 1024      |
 | `xl`   | 1440      |
 
-And these are our standard screen size ranges:
-
-- `small` (320px - 767px) Used for mobile-sized screens
-- `medium` (768px - 1023px) Used for tablet-sized screens
-- `large` - (1024px - 1439px) Used for laptop and small desktop screens
-- `extra-large` (≥1440px) Used for very large screens
-
-> Note: Some applications may only require a subset of screen sizes and not use all breakpoints.
+Standard screen size ranges:
 
-Our breakpoint system is customized within the theme object. `theme.canvas.breakpoints.values`.
+- `small` (320px - 767px) - Mobile screens
+- `medium` (768px - 1023px) - Tablet screens
+- `large` (1024px - 1439px) - Laptop/small desktop screens
+- `extra-large` (≥1440px) - Large screens
 
-```ts
-import {useTheme} from '@workday/canvas-kit-react/common';
-import {space} from '@workday/canvas-kit-react/tokens';
+### Using Breakpoints
 
-const {theme} = useTheme();
-const {values} = theme.canvas.breakpoints;
-const styles = {
-  [`@media (min-width: ${values.m}px)`]: {
-    padding: space.s,
-  },
-};
-```
-
-### Functions
-
-There are also several functions to help with generating media queries:
-
-- [Up](#Up)
-- [Down](#Down)
-- [Between](#Between)
-- [Only](#Only)
-
-#### Up
-
-_Returns a media query above the `min-width` for the range of a given breakpoint_
-
-Given a `start` breakpoint key ("zero", "s", "m", "l", "xl"), this function returns a media query
-(string) using a `min-width`.
+You can use standard CSS media queries:
 
-```ts
-import {useTheme} from '@workday/canvas-kit-react/common';
-import {space} from '@workday/canvas-kit-react/tokens';
-
-const theme = useTheme();
-const {up} = theme.canvas.breakpoints;
-const mediaQuery = up('l'); // Returns '@media (min-width: 1024px)'
-const styles = {
-  [mediaQuery]: {
-    padding: space.m,
-  },
-};
+```css
+@media (min-width: 768px) {
+  .my-component {
+    padding: 1rem;
+  }
+}
 ```
 
-#### Down
-
-_Returns a media query below the `max-width` for the range of a given breakpoint_
+---
 
-Given an `end` breakpoint key ("zero", "s", "m", "l", "xl"), this function returns a media query
-(string) using a `max-width`.
+## Deprecated API Reference
 
-> Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions. For
-> example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
+The following APIs are deprecated and should not be used in new code.
 
-If the `xl` breakpoint is provided, this function returns a media query with only a `min-width` of
-`0`, as seen in the second example below.
+### ~~CanvasProvider theme prop~~ (Deprecated)
 
-```ts
-import {useTheme} from '@workday/canvas-kit-react/common';
-import {space} from '@workday/canvas-kit-react/tokens';
-
-const theme = useTheme();
-const {down} = theme.canvas.breakpoints;
-const mediaQuery = down('m'); // Returns '@media (max-width: 1023.5px)'
-const styles = {
-  [mediaQuery]: {
-    padding: space.m,
-  },
-};
+```tsx
+// DEPRECATED - Do not use
+<CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
+  <App />
+</CanvasProvider>
 ```
 
-This example uses the `xl` breakpoint and only adds a `min-width` of `0` to the media query.
-
-```ts
-import {useTheme} from '@workday/canvas-kit-react/common';
-import {space} from '@workday/canvas-kit-react/tokens';
+### ~~useTheme / getTheme~~ (Deprecated)
 
+```tsx
+// DEPRECATED - Use CSS variables instead
 const theme = useTheme();
-const {down} = theme.canvas.breakpoints;
-const mediaQuery = down('xl'); // Returns '@media (min-width: 0)'
-const styles = {
-  [mediaQuery]: {
-    padding: space.m,
-  },
-};
+const theme = getTheme();
 ```
 
-#### Between
-
-_Returns a media query between two given breakpoints_
-
-Given `start` and `end` breakpoint keys ("zero", "s", "m", "l", "xl"), this function returns a media
-query (string) using a min-width and max-width.
+### ~~styled~~ (Deprecated)
 
-> Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions. For
-> example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
-
-If the `xl` breakpoint is provided, this function returns a media query with only a `min-width`, as
-seen in the second example below.
-
-```ts
-import {useTheme} from '@workday/canvas-kit-react/common';
-import {space} from '@workday/canvas-kit-react/tokens';
-
-const theme = useTheme();
-const {between} = theme.canvas.breakpoints;
-// Returns '@media (min-width: 320px) and (max-width: 1023.5px)'
-const mediaQuery = between('s', 'm');
-const styles = {
-  [mediaQuery]: {
-    padding: space.s,
-  },
-};
+```tsx
+// DEPRECATED - Use createStyles or createStencil instead
+import {styled} from '@workday/canvas-kit-react/common';
 ```
 
-This example uses `xl` as the `end` breakpoint and only adds a min-width to the media query.
+### ~~ContentDirection~~ (Deprecated)
 
-```ts
-import {useTheme} from '@workday/canvas-kit-react/common';
-import {space} from '@workday/canvas-kit-react/tokens';
-
-const theme = useTheme();
-const {between} = theme.canvas.breakpoints;
-const mediaQuery = between('m', 'xl'); // Returns '@media (min-width: 768px)'
-const styles = {
-  [mediaQuery]: {
-    padding: space.s,
-  },
-};
+```tsx
+// DEPRECATED - Use :dir() pseudo-class and CSS logical properties instead
+import {ContentDirection} from '@workday/canvas-kit-react/common';
 ```
 
-#### Only
-
-_Returns a media query with a `min-width` and `max-width` for a given breakpoint_
-
-Given a breakpoint key ("zero", "s", "m", "l", "xl"), this function returns a media query (string)
-using a `min-width` and `max-width`.
+### ~~defaultCanvasTheme~~ (Deprecated)
 
-> Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions.For
-> example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
-
-If the `xl` breakpoint is provided, this function returns a media query with only a `min-width` of
-`1440px`, as seen in the second example below.
-
-```ts
-import {useTheme} from '@workday/canvas-kit-react/common';
-import {space} from '@workday/canvas-kit-react/tokens';
-
-const theme = useTheme();
-const {only} = theme.canvas.breakpoints;
-const mediaQuery = only('s'); // Returns '@media (min-width: 320px) and (max-width: 767.5px)'
-const styles = {
-  [mediaQuery]: {
-    padding: space.s,
-  },
-};
+```tsx
+// DEPRECATED - Use defaultBranding instead
+import {defaultCanvasTheme} from '@workday/canvas-kit-react/common';
+// NEW - Use defaultBranding
+import {defaultBranding} from '@workday/canvas-kit-react/common';
 ```
 
-This example uses the `xl` breakpoint and only adds a `min-width` of `1440px` to the media query.
-
-```ts
-import {useTheme} from '@workday/canvas-kit-react/common';
-import {space} from '@workday/canvas-kit-react/tokens';
-
-const theme = useTheme();
-const {only} = theme.canvas.breakpoints;
-const mediaQuery = only('m', 'xl'); // Returns '@media (min-width: 1440px)'
-const styles = {
-  [mediaQuery]: {
-    padding: space.s,
-  },
-};
-```
+For detailed migration guidance, see our
+[Theming Documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs).

package/common/lib/theming/createCanvasTheme.ts

@@ -1,19 +1,20 @@
 import chroma from 'chroma-js';
+
 import colors from '@workday/canvas-colors-web';
+import {CanvasColor} from '@workday/canvas-kit-react/tokens';
+
+import {pickForegroundColor} from '../utils';
+// Should these be exported?
+import {deepMerge} from '../utils/deepMerge';
+import {memoize} from '../utils/memoize';
 import {defaultCanvasTheme} from './theme';
 import {
   CanvasTheme,
-  PartialCanvasTheme,
   CanvasThemePalette,
-  PartialCanvasThemePalette,
   ContentDirection,
+  PartialCanvasTheme,
+  PartialCanvasThemePalette,
 } from './types';
-import {CanvasColor} from '@workday/canvas-kit-react/tokens';
-import {pickForegroundColor} from '../utils';
-
-// Should these be exported?
-import {deepMerge} from '../utils/deepMerge';
-import {memoize} from '../utils/memoize';
 
 /**
  * @deprecated ⚠️ `shiftColor` is deprecated and will be removed in a future major version. While we work on an algorithm for color shifting, you can use [oklch from or with calc](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) to calculate colors.