@workday/canvas-kit-docs 14.0.0-alpha.1149-next.0 → 14.0.0-alpha.1153-next.0

package/dist/mdx/styling/mdx/WhyCanvasStyling.mdx

@@ -0,0 +1,136 @@
+# Why Canvas Styling
+
+This package contains everything needed to create CSS styling. This styling package contains a
+runtime for development and a static parsing process for build time.
+
+Here are the goals for this project:
+
+- TypeScript autocomplete of CSS object properties
+- Low runtime for development
+- Static CSS compilation for faster user experience
+- Static CSS extraction for CSS only packages
+- Dynamic styles using CSS Variables
+
+If you're using Canvas Kit and not directly using this package, there is nothing extra to do on your
+end. The Canvas Kit packages are using the static compilation as part of the build process. If you
+want to use this package for your own styles, you don't need to do anything special to use in
+development. Included is a small runtime to get styling working. If you wish to statically compile
+your CSS from your TypeScript files for faster page loading, visit the
+[Getting Started](/docs/styling-getting-started--docs) page.
+
+## Why?
+
+Canvas Kit no longer needs to support IE11 which allows us to use
+[CSS Custom Properties a.k.a. CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
+Dynamic style properties (properties that change during the lifecylce of the component) are the most
+costly in terms of performance in Emotion and should be avoided. Also, any conditionals in your
+Emotion style functions create unique hashes in the Emotion cache and makes that render frame pay an
+expensive
+[style recalculation](https://microsoftedge.github.io/DevTools/explainers/StyleTracing/explainer.html).
+
+We can avoid most of the cost of Emotion's runtime by using
+[@emotion/css](https://www.npmjs.com/package/@emotion/css) instead and hoist all style definitions
+outside of a component's render function. All dynamic styling can be moved into "modifiers" (from
+[BEM](https://getbem.com/introduction/#modifer:~:text=%2C%20header%20title-,Modifier,-A%20flag%20on)).
+
+There's still a runtime to select which styles should apply to an element and what the CSS Variable
+should be, but it is essentially only having to choose what CSS classes should apply to an element
+and changing the `style` property to set the CSS Variables. This does not require new
+[StyleSheet](https://developer.mozilla.org/en-US/docs/Web/API/StyleSheet) inserts which cause
+expensive style recalculation. Think of the runtime as being the following:
+
+```jsx
+<div
+  className={getClassNames(/* input from props */)}
+  style={getCSSVarValues(/* input from props */)}
+/>
+```
+
+For further information, please read our GitHub discussion on
+[the future of styling](https://github.com/Workday/canvas-kit/discussions/2265)
+
+## What is Canvas Kit Styling?
+
+Canvas Kit Styling includes two things:
+
+1. A utility function wrapper around `@emotion/css`
+2. An optional static compiler to remove most of the runtime
+
+### Utility Functions
+
+This packages provides three utility functions to make it easier to style element-based components.
+The following is a brief description of each function. If you'd like to read a more in-depth
+discussion of each, our [API docs](/docs/features-styling-api--create-styles).
+
+The primary utility function is the `createStyles` function. It makes a call to the `css` function
+from `@emotion/css`. Emotion still does most of the heavy lifting by handling the serialization,
+hashing, caching, and style injection.
+
+The other two utility functions, `createVars` and `createModifiers`, provide supplemental styling
+functionality. `createVars` allows you to create temporary CSS variables within components to create
+dynamic properties. And `createModifiers` creates a modifier function to create dynamic groups of
+properties. If you're familiar with modifiers in [BEM](https://getbem.com/introduction/) (Block,
+Element, Modifier) CSS, you're well on your way to understanding this function's intent.
+
+### Static Compiler
+
+The static compiler run as a TypeScript transform during TypeScript's transpilation phase. It
+requires the TypeScript type checker to determine the static value of any variables used. The
+transformer calls `@emotion/serialize` to pre-compute the serialized styles and hash so that
+`@emotion/css` can skip these steps. For example, there's the before/after of the code.
+
+```ts
+// before
+const myVars = createVars('textColor', 'backgroundColor');
+
+const myStyles = createStyles({
+  fontSize: 12,
+  color: cssVar(myVars.textColor),
+  backgroundColor: cssVar(myVars.backgroundColor),
+});
+
+// after
+const myVars = createVars('textColor', 'backgroundColor');
+
+const myStyles = createStyles({
+  name: 'a8g234',
+  styles:
+    'font-size: 12px; color: var(--css-my-vars-textColor); backgroundColor: var(--css-my-vars-backgroundColor);',
+});
+```
+
+Emotion has an internal shortcut that recognizes the `styles` property and
+[short-circuits interpolation](https://github.com/emotion-js/emotion/blob/f3b268f7c52103979402da919c9c0dd3f9e0e189/packages/serialize/src/index.js#L319).
+
+## Performance
+
+`createStyles` is more performant than `styled` components or the `css` prop because the styles must
+be statically evaluated. The actual characters of a CSS property value cannot change at runtime.
+This means we do not need to recalculate a hash every render or inject new `StyleSheet` entries into
+the `StyleSheetList` in a render cycle. Injecting new `StyleSheets` causes slow
+[Style Recalculation](https://web.dev/articles/reduce-the-scope-and-complexity-of-style-calculations).
+What is not well known is browser engines maintain an internal selector cache to make style
+recalculations as fast as possible. Adding a CSS class to a DOM element will invoke a style
+recalculation, but if the the CSS selector is already in the `StyleSheetList`, the browser can
+optimize how those styles are applied to the current element.
+
+In the runtime Emotion's case, a novel style will result in a new style hash which results in a new
+`StyleSheet` being injected into the `StyleSheetList`. To be safe, the browser's runtime engine will
+throw away any style recalculation cache and start from scratch. This happens if you render a new
+component on the page that hasn't been rendered yet, or if you make one of your style properties
+dynamic between render cycles. Eventually the Emotion cache gets warm and style recalcuation costs
+start to normalize and no longer invalidate the browser's selector cache.
+
+On a page with over 1,000 elements and over 1,000
+[CSSRules](https://developer.mozilla.org/en-US/docs/Web/API/CSSRule), (typical of a large web
+application), the difference between a &lt; 1ms for warmed selector cache and &gt; 100ms for a fresh
+selector cache. `createStyles` encourages a pattern similar to [BEM](https://getbem.com/) which
+works well with the browser's selector cache by not injecting new `StyleSheet`s during a page's
+normal operations. All styles are injected before any rendering takes place.
+
+> **Note:** Since style props force Emotion's dynamic rendering, style props will fall back to
+> Emotion's runtime performance characteristics and lose any benefits gained. Also if you use
+> `styled` components or the `css` prop in a tree that uses `createStyles`, the styles created by
+> the runtime APIs will still result in a selector cache invalidation. Even if you want to use
+> `styled` or the `css` prop, consider using CSS Variables for dynamic CSS property values to reduce
+> the performance overhead of Emotion.

package/dist/mdx/styling/mdx/examples/CSProp.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+
+import {createStencil, cssVar, px2rem} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+import {Card} from '@workday/canvas-kit-react/card';
+
+const myStencil = createStencil({
+  base: {
+    maxWidth: px2rem(400),
+    padding: system.space.zero,
+    overflow: 'hidden',
+  },
+});
+
+export default () => {
+  return (
+    <Card cs={myStencil()}>
+      <Card.Heading
+        cs={{
+          color: cssVar(system.color.text.inverse),
+          background: cssVar(system.color.bg.primary.default),
+          padding: cssVar(system.space.x3),
+        }}
+      >
+        The Future of Styling
+      </Card.Heading>
+      <Card.Body cs={{padding: cssVar(system.space.x3)}}>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas blandit consectetur.
+        Nam in congue mauris. Ut non metus a arcu rutrum accumsan. Duis luctus, diam vitae iaculis
+        semper, nibh nisl varius erat, vitae dapibus velit lacus blandit tellus. Aenean vestibulum
+        porta lectus non mollis. Quisque in lacus vitae sem vulputate rutrum. Sed dapibus aliquam
+        dui, eu aliquam purus egestas eu.
+      </Card.Body>
+    </Card>
+  );
+};

package/dist/mdx/styling/mdx/examples/CreateModifiers.tsx

@@ -0,0 +1,27 @@
+import React from 'react';
+
+import {createStyles, createModifiers} from '@workday/canvas-kit-styling';
+
+const myModifiers = createModifiers({
+  size: {
+    large: createStyles({
+      backgroundColor: 'lightgray',
+      width: 100,
+      height: 100,
+    }),
+    small: createStyles({
+      backgroundColor: 'lightgray',
+      width: 50,
+      height: 50,
+    }),
+  },
+});
+
+export default () => {
+  return (
+    <>
+      <div className={myModifiers({size: 'large'})}>Large</div>
+      <div className={myModifiers({size: 'small'})}>Small</div>
+    </>
+  );
+};

package/dist/mdx/styling/mdx/examples/CreateStencil.tsx

@@ -0,0 +1,63 @@
+import * as React from 'react';
+import {createStencil} from '@workday/canvas-kit-styling';
+import {Card} from '@workday/canvas-kit-react/card';
+import {system} from '@workday/canvas-tokens-web';
+import {Switch} from '@workday/canvas-kit-react/switch';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+
+const themedCardStencil = createStencil({
+  vars: {
+    // Create CSS variables for the color of the header
+    headerColor: '',
+  },
+  parts: {
+    // Allows for styling a sub element of the component that may not be exposed through the API
+    header: 'themed-card-header',
+    body: 'themed-card-body',
+  },
+  base: ({headerPart, headerColor}) => ({
+    padding: system.space.x4,
+    boxShadow: system.depth[2],
+    backgroundColor: system.color.bg.default,
+    color: system.color.text.default,
+    // Targets the header part via [data-part="themed-card-header"]"]
+    [headerPart]: {
+      color: headerColor,
+    },
+  }),
+  modifiers: {
+    isDarkTheme: {
+      // If the prop `isDarkTheme` is true, style the component and it's parts
+      true: ({headerPart, bodyPart}) => ({
+        backgroundColor: system.color.bg.contrast.default,
+        color: system.color.text.inverse,
+        [`${headerPart}, ${bodyPart}`]: {
+          color: system.color.text.inverse,
+        },
+      }),
+    },
+  },
+});
+
+export default ({isDarkTheme, headerColor, elemProps}) => {
+  const [darkTheme, setIsDarkTheme] = React.useState(false);
+  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setIsDarkTheme(event.target.checked);
+  };
+  return (
+    <div>
+      <FormField>
+        <FormField.Label>Toggle Dark Theme</FormField.Label>
+        <FormField.Input as={Switch} onChange={handleChange} checked={darkTheme} />
+      </FormField>
+
+      <Card cs={themedCardStencil({isDarkTheme: darkTheme, headerColor})} {...elemProps}>
+        <Card.Heading {...themedCardStencil.parts.header}>Canvas Supreme</Card.Heading>
+        <Card.Body {...themedCardStencil.parts.body}>
+          Our house special supreme pizza includes pepperoni, sausage, bell peppers, mushrooms,
+          onions, and oregano.
+        </Card.Body>
+      </Card>
+    </div>
+  );
+};

package/dist/mdx/styling/mdx/examples/CreateStyles.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+
+import {createStyles} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = createStyles({
+  background: system.color.bg.primary.default,
+  color: system.color.text.inverse,
+});
+
+export default () => {
+  return <button className={styles}>Click Me</button>;
+};

package/dist/mdx/styling/mdx/examples/CreateVars.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+
+import {createStyles, createVars, cssVar} from '@workday/canvas-kit-styling';
+
+const myVars = createVars('background');
+
+const styles = createStyles({
+  width: 100,
+  height: 100,
+  backgroundColor: cssVar(myVars.background),
+});
+
+export default () => {
+  return (
+    <>
+      <div className={styles} style={myVars({background: 'gray'})} />
+      <div className={styles} style={myVars({background: 'blue'})} />
+    </>
+  );
+};

package/dist/mdx/styling/mdx/examples/CustomButton.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+
+import {system} from '@workday/canvas-tokens-web';
+import {plusIcon} from '@workday/canvas-system-icons-web';
+import {createStencil, handleCsProp, px2rem} from '@workday/canvas-kit-styling';
+import {createComponent} from '@workday/canvas-kit-react/common';
+import {
+  BaseButton,
+  buttonStencil,
+  PrimaryButton,
+  PrimaryButtonProps,
+} from '@workday/canvas-kit-react/button';
+import {systemIconStencil} from '@workday/canvas-kit-react/icon';
+import {Grid} from '@workday/canvas-kit-react/layout';
+
+const myButtonStencil = createStencil({
+  extends: buttonStencil,
+  base: {
+    [buttonStencil.vars.background]: system.color.static.green.soft,
+    [buttonStencil.vars.label]: system.color.static.green.strong,
+    [systemIconStencil.vars.color]: system.color.static.green.strong,
+    [buttonStencil.vars.borderRadius]: system.shape.half,
+    border: `${px2rem(3)} solid transparent`,
+    width: 'fit-content',
+    '&:hover': {
+      [buttonStencil.vars.background]: system.color.static.green.default,
+      border: `${px2rem(3)} dotted ${system.color.static.green.strong}`,
+      [systemIconStencil.vars.color]: system.color.static.green.strong,
+    },
+    '&:active': {
+      [buttonStencil.vars.background]: system.color.static.green.strong,
+      [buttonStencil.vars.label]: system.color.fg.inverse,
+      [systemIconStencil.vars.color]: system.color.fg.inverse,
+    },
+  },
+  modifiers: {
+    size: {
+      small: {
+        padding: system.space.x4,
+      },
+      medium: {
+        padding: system.space.x6,
+      },
+      large: {
+        padding: system.space.x8,
+      },
+    },
+  },
+});
+
+const MyButton = createComponent('button')({
+  Component: ({children, size, ...elemProps}: PrimaryButtonProps, ref, Element) => (
+    <Element ref={ref} {...handleCsProp(elemProps, myButtonStencil({size}))}>
+      {children}
+    </Element>
+  ),
+});
+
+export default () => (
+  <Grid cs={{gap: px2rem(4), gridTemplateColumns: 'repeat(3, 1fr)', alignItems: 'center'}}>
+    <MyButton icon={plusIcon}>My Button</MyButton>
+    <MyButton size="medium" icon={plusIcon} iconPosition="end">
+      Medium My Button
+    </MyButton>
+    <MyButton size="large" icon={plusIcon}>
+      Large My Button
+    </MyButton>
+  </Grid>
+);

package/dist/mdx/styling/mdx/examples/CustomIcon.tsx

@@ -0,0 +1,23 @@
+import React from 'react';
+import {createStencil, handleCsProp} from '@workday/canvas-kit-styling';
+import {systemIconStencil} from '@workday/canvas-kit-react/icon';
+import {system} from '@workday/canvas-tokens-web';
+
+const myIconStencil = createStencil({
+  extends: systemIconStencil,
+  base: {
+    [systemIconStencil.vars.color]: system.color.icon.primary.default,
+    [systemIconStencil.vars.accentColor]: system.color.icon.critical.default,
+    [systemIconStencil.vars.size]: system.space.x4,
+  },
+});
+
+export default elemProps => (
+  <span {...handleCsProp(elemProps, myIconStencil())}>
+    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 80 20">
+      <circle className="wd-icon-fill" cx="10" cy="10" r="10" />
+      <circle className="wd-icon-accent" cx="40" cy="10" r="10" />
+      <circle className="wd-icon-fill" cx="70" cy="10" r="10" />
+    </svg>
+  </span>
+);

package/dist/mdx/styling/mdx/examples/EmotionButton.tsx

@@ -0,0 +1,111 @@
+import React from 'react';
+import styled from '@emotion/styled';
+
+interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'danger';
+  size: 'large' | 'medium' | 'small';
+  backgroundColor?: string;
+  children?: React.ReactNode;
+}
+
+const StyledButton = styled('button')<ButtonProps>(
+  {
+    // base styles
+    fontSize: '1rem',
+    display: 'flex',
+    borderRadius: '1rem',
+  },
+  // variant styles
+  ({variant, backgroundColor}) => {
+    switch (variant) {
+      case 'primary':
+        return {
+          background: backgroundColor || 'blue',
+          color: 'white',
+        };
+      case 'secondary':
+        return {
+          background: backgroundColor || 'gray',
+        };
+      case 'danger':
+        return {
+          background: backgroundColor || 'red',
+        };
+      default:
+        return {};
+    }
+  },
+  // size styles
+  ({size}) => {
+    switch (size) {
+      case 'large':
+        return {
+          fontSize: '1.4rem',
+          height: '2rem',
+        };
+      case 'medium':
+        return {
+          fontSize: '1rem',
+          height: '1.5rem',
+        };
+      case 'small':
+        return {
+          fontSize: '0.8rem',
+          height: '1.2rem',
+        };
+      default:
+        return {};
+    }
+  }
+);
+
+export default () => {
+  return (
+    <div style={{display: 'flex', flexDirection: 'column', gap: '1rem'}}>
+      <div style={{display: 'flex', gap: '1rem'}}>
+        <StyledButton variant="primary" size="large">
+          Primary Large
+        </StyledButton>
+        <StyledButton variant="primary" size="medium">
+          Primary Medium
+        </StyledButton>
+        <StyledButton variant="primary" size="small">
+          Primary Small
+        </StyledButton>
+      </div>
+      <div style={{display: 'flex', gap: '1rem'}}>
+        <StyledButton variant="secondary" size="large">
+          Secondary Large
+        </StyledButton>
+        <StyledButton variant="secondary" size="medium">
+          Secondary Medium
+        </StyledButton>
+        <StyledButton variant="secondary" size="small">
+          Secondary Small
+        </StyledButton>
+      </div>
+      <div style={{display: 'flex', gap: '1rem'}}>
+        <StyledButton variant="danger" size="large">
+          Danger Large
+        </StyledButton>
+        <StyledButton variant="danger" size="medium">
+          Danger Medium
+        </StyledButton>
+        <StyledButton variant="danger" size="small">
+          Danger Small
+        </StyledButton>
+      </div>
+      <div style={{display: 'flex', gap: '1rem'}}>
+        <StyledButton variant="danger" size="large" backgroundColor="orange">
+          Custom Large
+        </StyledButton>
+        <StyledButton variant="danger" size="medium" backgroundColor="orange">
+          Custom Medium
+        </StyledButton>
+        <StyledButton variant="danger" size="small" backgroundColor="orange">
+          Custom Small
+        </StyledButton>
+      </div>
+    </div>
+  );
+};

package/dist/mdx/styling/mdx/examples/ManualStylesButton.tsx

@@ -0,0 +1,107 @@
+import React from 'react';
+import {createStyles} from '@workday/canvas-kit-styling';
+
+interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'danger';
+  size: 'large' | 'medium' | 'small';
+  backgroundColor?: string;
+  children?: React.ReactNode;
+}
+
+const baseStyles = createStyles({
+  fontSize: '1rem',
+  display: 'flex',
+  borderRadius: '1rem',
+});
+
+const modifierStyles = {
+  variant: {
+    primary: createStyles({
+      background: `var(--button-background-color, blue)`,
+      color: 'white',
+    }),
+    secondary: createStyles({
+      background: `var(--button-background-color, gray)`,
+    }),
+    danger: createStyles({
+      background: `var(--button-background-color, red)`,
+    }),
+  },
+  size: {
+    large: createStyles({
+      fontSize: '1.4rem',
+      height: '2rem',
+    }),
+    medium: createStyles({
+      fontSize: '1rem',
+      height: '1.5rem',
+    }),
+    small: createStyles({
+      fontSize: '0.8rem',
+      height: '1.2rem',
+    }),
+  },
+};
+
+const Button = ({variant, size, backgroundColor, children}: ButtonProps) => {
+  const className = [baseStyles, modifierStyles.variant[variant], modifierStyles.size[size]].join(
+    ' '
+  );
+  const style = {'--button-background-color': backgroundColor} as React.CSSProperties;
+  return (
+    <button className={className} style={style}>
+      {children}
+    </button>
+  );
+};
+
+export default () => {
+  return (
+    <div style={{display: 'flex', flexDirection: 'column', gap: '1rem'}}>
+      <div style={{display: 'flex', gap: '1rem'}}>
+        <Button variant="primary" size="large">
+          Primary Large
+        </Button>
+        <Button variant="primary" size="medium">
+          Primary Medium
+        </Button>
+        <Button variant="primary" size="small">
+          Primary Small
+        </Button>
+      </div>
+      <div style={{display: 'flex', gap: '1rem'}}>
+        <Button variant="secondary" size="large">
+          Secondary Large
+        </Button>
+        <Button variant="secondary" size="medium">
+          Secondary Medium
+        </Button>
+        <Button variant="secondary" size="small">
+          Secondary Small
+        </Button>
+      </div>
+      <div style={{display: 'flex', gap: '1rem'}}>
+        <Button variant="danger" size="large">
+          Danger Large
+        </Button>
+        <Button variant="danger" size="medium">
+          Danger Medium
+        </Button>
+        <Button variant="danger" size="small">
+          Danger Small
+        </Button>
+      </div>
+      <div style={{display: 'flex', gap: '1rem'}}>
+        <Button variant="danger" size="large" backgroundColor="orange">
+          Custom Large
+        </Button>
+        <Button variant="danger" size="medium" backgroundColor="orange">
+          Custom Medium
+        </Button>
+        <Button variant="danger" size="small" backgroundColor="orange">
+          Custom Small
+        </Button>
+      </div>
+    </div>
+  );
+};

package/dist/mdx/styling/mdx/examples/StyledButton.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+
+import {system} from '@workday/canvas-tokens-web';
+import {caretDownIcon} from '@workday/canvas-system-icons-web';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {buttonStencil, PrimaryButton} from '@workday/canvas-kit-react/button';
+import {systemIconStencil} from '@workday/canvas-kit-react/icon';
+
+const varStyles = createStyles({
+  [buttonStencil.vars.background]: system.color.static.gray.soft,
+  [buttonStencil.vars.label]: system.color.static.blue.strong,
+  // Because PrimaryButton uses SystemIcon under the hood,
+  // we also can change system icon variable for color
+  [systemIconStencil.vars.color]: system.color.static.blue.strong,
+  '&:hover': {
+    [buttonStencil.vars.background]: system.color.static.amber.default,
+    [buttonStencil.vars.label]: system.color.static.white,
+    [systemIconStencil.vars.color]: system.color.static.white,
+  },
+  '&:focus-visible': {
+    [buttonStencil.vars.background]: system.color.static.green.default,
+    [buttonStencil.vars.boxShadowOuter]: system.color.static.green.strong,
+    [buttonStencil.vars.boxShadowInner]: system.color.static.white,
+  },
+});
+
+export default () => (
+  <PrimaryButton cs={varStyles} icon={caretDownIcon} iconPosition="end">
+    Overwrite styles by setting variables
+  </PrimaryButton>
+);