@workday/canvas-kit-react 6.0.0-alpha.0-next.26 → 6.0.0-alpha.0-next.27

package/action-bar/lib/ActionBar.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import styled from '@emotion/styled';
-import {colors, commonColors, space} from '@workday/canvas-kit-react/tokens';
+import {styled} from '@workday/canvas-kit-react/common';
+import {colors, commonColors, space, CSSProperties} from '@workday/canvas-kit-react/tokens';
 
 export interface ActionBarProps extends React.HTMLAttributes<HTMLDivElement> {
   /**
@@ -10,45 +10,58 @@ export interface ActionBarProps extends React.HTMLAttributes<HTMLDivElement> {
   fixed?: boolean;
 }
 
-const ActionBarContainer = styled('div')(
+function getFixedStyles(fixed = false): CSSProperties {
+  return fixed
+    ? {
+        position: 'fixed',
+        left: 0,
+        bottom: 0,
+        right: 0,
+      }
+    : {};
+}
+
+const ActionBarContainer = styled('div')<ActionBarProps>(
   {
     borderTop: `solid 1px ${colors.soap400}`,
     background: commonColors.background,
     padding: space.s,
     boxShadow: '0 -2px 4px rgba(0, 0, 0, 0.08)',
-    '@media (max-width: 575px)': {
-      padding: space.xxs,
-    },
   },
-  ({fixed}: ActionBarProps) =>
-    fixed && {
-      position: 'fixed',
-      left: 0,
-      bottom: 0,
-      right: 0,
-    }
+  ({fixed, theme}) => {
+    return {
+      ...getFixedStyles(fixed),
+      [theme.canvas.breakpoints.down('s')]: {
+        padding: space.xxs,
+      },
+    };
+  }
 );
 
-const ChildrenContainer = styled('div')({
-  display: 'inline-block',
-  padding: `0 ${space.m}`,
-  '*:not(:first-of-type)': {
-    marginLeft: space.s,
+const ChildrenContainer = styled('div')(
+  {
+    display: 'inline-block',
+    padding: `0 ${space.m}`,
+    '*:not(:first-of-type)': {
+      marginLeft: space.s,
+    },
   },
-  '@media (max-width: 575px)': {
-    display: 'flex',
-    padding: space.xxs,
-    justifyContent: 'center',
-    flexDirection: 'row-reverse',
-    '> *': {
-      flex: 1,
-      '&:not(:first-of-type)': {
-        marginRight: space.s,
-        marginLeft: 0,
+  ({theme}) => ({
+    [theme.canvas.breakpoints.down('s')]: {
+      display: 'flex',
+      padding: space.xxs,
+      justifyContent: 'center',
+      flexDirection: 'row-reverse',
+      '> *': {
+        flex: 1,
+        '&:not(:first-of-type)': {
+          marginRight: space.s,
+          marginLeft: 0,
+        },
       },
     },
-  },
-});
+  })
+);
 
 export default class ActionBar extends React.Component<ActionBarProps> {
   public render() {

package/common/lib/theming/README.md

@@ -90,10 +90,10 @@ export const defaultCanvasTheme: CanvasTheme = {
   breakpoints: {
     values: {
       zero: 0,
-      s: 600,
-      m: 960,
-      l: 1280,
-      xl: 1920,
+      s: 320,
+      m: 768,
+      l: 1024,
+      xl: 1440,
     },
     up,
     down,
@@ -243,41 +243,205 @@ variable before falling back to the default theme.
 
 ## Breakpoints
 
-Our breakpoint system is customized within the theme object. `theme.breakpoints.values` contains the
-various widths that our components adjust at:
+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.
+
+### 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         |
-| `s`    | 600       |
-| `m`    | 960       |
-| `l`    | 1280      |
-| `xl`   | 1920      |
+| `s`    | 320       |
+| `m`    | 768       |
+| `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.
+
+Our breakpoint system is customized within the theme object. `theme.canvas.breakpoints.values`.
+
+```ts
+import {useTheme} from '@workday/canvas-kit-react/common';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+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: (key: BreakpointFnParam) => string`
+- [Up](#Up)
+- [Down](#Down)
+- [Between](#Between)
+- [Only](#Only)
 
-> Returns a media query reflecting your specified size and up. Works with the enum (e.g.
-> BreakpointKey.m) or the string (e.g. 'm'). Example: theme.breakpoints.up(BreakpointKey.m) =>
-> '@media (min-width:960px)'
+#### Up
 
-#### `down: (key: BreakpointFnParam) => string`
+_Returns a media query above the `min-width` for the range of a given breakpoint_
 
-> Returns a media query reflecting your specified size and down. Works with the enum or the string
-> (e.g. 'm'). Example: theme.breakpoints.down(BreakpointKey.m) => '@media (max-width:1279.5px)'
+Given a `start` breakpoint key ("zero", "s", "m", "l", "xl"), this function returns a media query
+(string) using a `min-width`.
 
-#### `between: (start: BreakpointFnParam, end: BreakpointFnParam) => string`
+```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,
+  },
+};
+```
 
-> Returns a media query reflecting the sizes between your specified breakpoints. Works with the enum
-> or the string (e.g. 'm'). Example: theme.breakpoints.between(BreakpointKey.m, BreakpointKey.l) =>
-> '@media (min-width:960px) and (max-width:1919.5px)'
+#### 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`.
+
+> 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
+`0`, 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 {down} = theme.canvas.breakpoints;
+const mediaQuery = down('m'); // Returns '@media (max-width: 1023.5px)'
+const styles = {
+  [mediaQuery]: {
+    padding: space.m,
+  },
+};
+```
+
+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';
+
+const theme = useTheme();
+const {down} = theme.canvas.breakpoints;
+const mediaQuery = down('xl'); // Returns '@media (min-width: 0)'
+const styles = {
+  [mediaQuery]: {
+    padding: space.m,
+  },
+};
+```
 
-#### `only: (key: BreakpointFnParam) => string`
+#### Between
 
-> Returns a media query reflecting the size within your specified breakpoint. Works with the enum or
-> the string (e.g. 'm'). Example: theme.breakpointsonly(BreakpointKey.m) => '@media
-> (min-width:960px) and (max-width:1279.5px)'
+_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.
+
+> 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,
+  },
+};
+```
+
+This example uses `xl` as the `end` breakpoint and only adds a min-width 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 {between} = theme.canvas.breakpoints;
+const mediaQuery = between('m', 'xl'); // Returns '@media (min-width: 768px)'
+const styles = {
+  [mediaQuery]: {
+    padding: space.s,
+  },
+};
+```
+
+#### 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`.
+
+> 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,
+  },
+};
+```
+
+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,
+  },
+};
+```
 
 ## useIsRTL Hook
 

package/common/lib/theming/breakpoints.ts

@@ -9,43 +9,278 @@ export enum BreakpointKey {
 export type BreakpointFnParam = BreakpointKey | keyof typeof BreakpointKey;
 
 export type CanvasBreakpoints = {
-  zero: number;
-  s: number;
-  m: number;
-  l: number;
-  xl: number;
+  /**
+   * ### Zero Breakpoint
+   *
+   * This breakpoint is useful when you need to set a media query `min-width` below small.
+   *
+   * @example
+   * ```ts
+   * import { useTheme } from '@workday/canvas-kit-react/common';
+   * import { space } from '@workday/canvas-kit-react/tokens';
+   *
+   * const theme = useTheme();
+   * const { values } = theme.canvas.breakpoints;
+   * const styles = {
+   *   [`@media (min-width: ${values.zero}px)`]: {
+   *     padding: space.xxs,
+   *   },
+   * }
+   * ```
+   */
+  zero: 0;
+  /**
+   * ### Small Breakpoint
+   *
+   * The small breakpoint provides the `min-width` for mobile devices, such as phones and tablets.
+   * This size ranges from a min-width of 320px to a max-width of 767px.
+   *
+   * @example
+   * ```ts
+   * import { useTheme } from '@workday/canvas-kit-react/common';
+   * import { space } from '@workday/canvas-kit-react/tokens';
+   *
+   * const theme = useTheme();
+   * const { values } = theme.canvas.breakpoints;
+   * const styles = {
+   *   [`@media (min-width: ${values.s}px)`]: {
+   *     padding: space.xs,
+   *   },
+   * }
+   * ```
+   */
+  s: 320;
+  /**
+   * ### Medium Breakpoint
+   *
+   * The medium breakpoint is the min-width for intended for medium screens, such as laptops.
+   * This size ranges from a min-width of 768px to a max-width of 1023px.
+   *
+   * @example
+   * ```ts
+   * import { useTheme } from '@workday/canvas-kit-react/common';
+   * import { space } from '@workday/canvas-kit-react/tokens';
+   *
+   * const theme = useTheme();
+   * const { values } = theme.canvas.breakpoints;
+   * const styles = {
+   *   [`@media (min-width: ${values.m}px)`]: {
+   *     padding: space.s,
+   *   },
+   * }
+   * ```
+   */
+  m: 768;
+  /**
+   * ### Large Breakpoint
+   *
+   * The large breakpoint is the min-width for intended for large screens, such as desktops.
+   * This size ranges from a min-width of 1024px to a max-width of 1439px.
+   *
+   * @example
+   * ```ts
+   * import { useTheme } from '@workday/canvas-kit-react/common';
+   * import { space } from '@workday/canvas-kit-react/tokens';
+   *
+   * const theme = useTheme();
+   * const { values } = theme.canvas.breakpoints;
+   * const styles = {
+   *   [`@media (min-width: ${values.m}px)`]: {
+   *     padding: space.s,
+   *   },
+   * }
+   * ```
+   */
+  l: 1024;
+  /**
+   * ### Extra-Large Breakpoint
+   *
+   * The large breakpoint is the min-width for intended for extra-large screens, such as wide monitors and TVs.
+   * This size has a min-width of 1440px and no max-width.
+   *
+   * @example
+   * ```ts
+   * import { useTheme } from '@workday/canvas-kit-react/common';
+   * import { space } from '@workday/canvas-kit-react/tokens';
+   *
+   * const theme = useTheme();
+   * const { values } = theme.canvas.breakpoints;
+   * const styles = {
+   *   [`@media (min-width: ${values.m}px)`]: {
+   *     padding: space.s
+   *   },
+   * }
+   * ```
+   */
+  xl: 1440;
 };
 
 export const breakpointKeys = ['zero', 's', 'm', 'l', 'xl'] as const;
 
+/**
+ * ### Theme Breakpoint Values
+ *
+ * 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. This object provides five breakpoint values
+ * that correspond to the min-widths of our standard screen sizes.
+ *
+ * - `zero`: 0
+ * - `s`: 320
+ * - `m`: 768
+ * - `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.
+ *
+ */
 export const breakpoints: CanvasBreakpoints = {
   zero: 0,
-  s: 600,
-  m: 960,
-  l: 1280,
-  xl: 1920,
+  s: 320,
+  m: 768,
+  l: 1024,
+  xl: 1440,
 };
 
 const step = 0.5;
 
+/**
+ * ### 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`.
+ *
+ * @example
+ * ```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,
+ *   }
+ * };
+ * ```
+ */
 export function up(key: BreakpointFnParam) {
   const value = typeof breakpoints[key as BreakpointKey] === 'number' ? breakpoints[key] : key;
-  return `@media (min-width:${value}px)`;
+  return `@media (min-width: ${value}px)`;
 }
 
-export function down(key: BreakpointFnParam) {
-  const endIndex = breakpointKeys.indexOf(key as BreakpointKey) + 1;
+/**
+ * ### 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`.
+ *
+ * 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 `0`,
+ * as seen in the second example below.
+ *
+ * @example
+ * ```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,
+ *   }
+ * };
+ * ```
+ *
+ * This example uses the `xl` breakpoint and only adds a `min-width` of `0` to the media query.
+ * @example
+ * ```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('xl'); // Returns '@media (min-width: 0)'
+ * const styles = {
+ *   [mediaQuery]: {
+ *     padding: space.m,
+ *   }
+ * };
+ * ```
+ */
+export function down(endKey: BreakpointFnParam) {
+  const endIndex = breakpointKeys.indexOf(endKey as BreakpointKey) + 1;
   const upperbound = breakpoints[breakpointKeys[endIndex]];
-
   if (endIndex === breakpointKeys.length) {
     // xl down applies to all sizes
     return up(BreakpointKey.zero);
   }
 
   const value = typeof upperbound === 'number' && endIndex > 0 ? upperbound : 0;
-  return `@media (max-width:${value - step}px)`;
+  return `@media (max-width: ${value - step}px)`;
 }
 
+/**
+ * ### 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.
+ *
+ * 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.
+ *
+ * @example
+ * ```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,
+ *   }
+ * };
+ * ```
+ *
+ * This example uses `xl` as the `end` breakpoint and only adds a min-width to the media query.
+ * @example
+ * ```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,
+ *   }
+ * };
+ * ```
+ */
 export function between(start: BreakpointFnParam, end: BreakpointFnParam) {
   const endIndex = breakpointKeys.indexOf(end) + 1;
 
@@ -54,11 +289,56 @@ export function between(start: BreakpointFnParam, end: BreakpointFnParam) {
   }
 
   return (
-    `@media (min-width:${breakpoints[start]}px) and ` +
-    `(max-width:${breakpoints[breakpointKeys[endIndex]] - step}px)`
+    `@media (min-width: ${breakpoints[start]}px) and ` +
+    `(max-width: ${breakpoints[breakpointKeys[endIndex]] - step}px)`
   );
 }
 
+/**
+ * ### 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`.
+ *
+ * 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.
+ *
+ * @example
+ * ```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,
+ *   }
+ * };
+ * ```
+ *
+ * This example uses the `xl` breakpoint and only adds a `min-width` of `1440px` to the media query.
+ * @example
+ * ```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('xl'); // Returns '@media (min-width: 1440px)'
+ * const styles = {
+ *   [mediaQuery]: {
+ *     padding: space.s,
+ *   }
+ * };
+ * ```
+ */
 export function only(key: BreakpointFnParam) {
   return between(key, key);
 }