@workday/canvas-kit-docs 14.0.0-alpha.1148-next.0 → 14.0.0-alpha.1151-next.0

package/dist/mdx/styling/mdx/CreateStyles.mdx

@@ -0,0 +1,111 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+import {InformationHighlight} from '@workday/canvas-kit-preview-react/information-highlight';
+import {system} from '@workday/canvas-tokens-web'
+
+import CreateStyles from './examples/CreateStyles';
+
+
+# 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.
+
+## Basic Example
+
+In this example, the HTML will look like:
+
+```html
+<div class="css-m39zwu"></div>
+```
+
+The CSS will look like this:
+
+```css
+.css-m39zwu {
+  background: var(--cnvs-sys-color-bg-primary-default);
+  color: var(--cnvs-sys-color-text-inverse);
+}
+```
+<InformationHighlight className="sb-unstyled" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading> Note</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		The `createStyles` function handles wrapping our Tokens in `var(--${token})`.
+	</InformationHighlight.Body>
+</InformationHighlight>
+
+We're using `className` for simplicity here.
+
+<ExampleCodeBlock code={CreateStyles} />
+
+<InformationHighlight className="sb-unstyled" variant="caution" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading> Caution: Performance Hit</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		Do not inline the call to `createStyles` in the render function of a component. This will cause performance issues as a new style is inserted into the browser on every render.
+	</InformationHighlight.Body>
+</InformationHighlight>
+
+```tsx
+// Bad example (inside render function)
+import {system} from '@workday/canvas-tokens-webs';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+function MyComponent() {
+  const styles = createStyles({color: system.color.static.red.default}); // Don't do this
+  return <PrimaryButton className={createStyles({color: system.color.static.red.default})}>Text</PrimaryButton>;
+}
+```
+
+## When to Use `createStyles`
+
+`createStyles` is a great way to generate static styles when styling our components that don't rely
+on dynamic styles. Use `createStyles` if you want to create re useable styles or need to apply
+simple style overrides to our components.
+
+## When to Use Something Else
+
+You should use [stencils](/docs/styling-getting-started-stencils--docs) when styling our components
+that have complex styles and dynamic properties.
+
+## Proper Usage
+
+```tsx
+// Bad example (inside render function)
+import {system} from '@workday/canvas-tokens-webs';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+function MyComponent() {
+  const styles = createStyles({color: system.color.static.red.default}); // Don't do this
+  return <PrimaryButton cs={styles}>Text</PrimaryButton>;
+}
+
+// Good example (outside render function)
+import {system} from '@workday/canvas-tokens-webs';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+const styles = createStyles({color: system.color.static.red.default});
+
+function MyComponent() {
+  return <PrimaryButton cs={styles}>Text</PrimaryButton>;
+}
+```
+
+<InformationHighlight className="sb-unstyled" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading>Note</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		Most of our components support using the `cs` prop to apply the static styles. It merges everything together and applies `className` and `style` attributes to a React element
+	</InformationHighlight.Body>
+</InformationHighlight>
+
+
+
+## Performance Benefits
+
+`createStyles` is performant because:
+
+- Styles are statically evaluated when styles are defined outside the render function
+- No new StyleSheets are injected during render
+- It works well with the browser's selector cache

package/dist/mdx/styling/mdx/CustomizingStyles.mdx

@@ -0,0 +1,179 @@
+# How To Customize Styles
+
+There are multiple ways to customize styles for components within Canvas Kit. The approach you
+choose will depend on your use case. Ranging from some simple overrides to fully custom solutions,
+here are the following options:
+
+- [Create Styles](#createstyles)
+- [Stencils](#stencils)
+
+## Create Styles
+
+### Using `createStyles` with `cs` prop
+
+Use `createStyles` in tandem with `cs` prop when you're overriding static styles and making small modifications to an
+existing Canvas Kit component like padding, color and flex properties. Take our `Text` component as
+an example.
+
+```tsx
+import {createStyles} from '@Workday/canvas-kit-styling';
+import {system} from '@Workday/canvas-tokens-web';
+import {Text} from '@Workday/canvas-kit-react/text';
+
+const uppercaseTextStyles = createStyles({
+  textTransform: 'uppercase',
+  margin: system.space.x4
+})
+//...
+<Text cs={uppercaseTextStyles}>My uppercased text</Text>;
+```
+
+> **Note:** `createStyles` handles wrapping our token variables in `var(--${token})`
+
+You can also apply styles created via `createStyles` via `className`.
+
+```tsx
+import {createStyles} from '@Workday/canvas-kit-styling';
+import {system} from '@Workday/canvas-tokens-web';
+import {Text} from '@Workday/canvas-kit-react/text';
+
+const uppercaseTextStyles = createStyles({
+  textTransform: 'uppercase',
+  margin: system.space.x4
+})
+//...
+<Text className={uppercaseTextStyles}>My uppercased text</Text>;
+```
+
+If you need to dynamically apply styles based on some state or prop, use [Stencils](#stencils) instead.
+
+
+## Stencils
+
+Stencils can be useful when applying dynamic styles or building your own reusable component.
+
+### Extending Stencils
+
+[Stencils](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--create-stencil) help you
+organize the styling of reusable components into base styles, modifiers, and variables. The
+organization makes it more natural to produce static and clean CSS with optional extraction into CSS
+files.
+
+Stencils that define variables, modifiers and base styles can be extended to create your own
+reusable component using Canvas Kit styles.
+
+If we take `SystemIcon` component as an example, it defines `systemIconStencil` which defines styles
+for an icon. This stencil can be extended to build a custom icon component for your use case.
+
+**Before v11** you'd have to use `systemIconStyles` function to overwrite styles for an icon:
+
+```tsx
+// Before v11
+import {systemIconStyles} from '@workday/canvas-kit-react';
+import {space} from '@workday/canvas-kit-react/tokens'; // old tokens
+
+// old way of styling with Emotion styled
+const StyledNavIcon = styled('span')(({size, iconStyles}){
+  display: 'inline-flex',
+  pointerEvents: 'unset',
+  margin: `${space.xxxs} ${space.xxxs} 0 0`,
+  padding: '0',
+  'svg': {
+    ...iconStyles,
+    width: size,
+    height: size,
+  }
+});
+
+const NavIcon = ({iconColor, iconHover, iconBackground, iconBackgroundHover, icon, size}) => {
+  // old way of styling with systemIconStyles function
+  // systemIconStyles is deprecated in v11
+  const iconStyles = systemIconStyles({
+    fill: iconColor,
+    fillHover: iconHover,
+    background: iconBackground,
+    backgroundHover: iconBackgroundHover,
+  });
+
+  // insert icon function used by platform or any other functionality here
+
+  return (
+    <StyledNavIcon
+      icon={icon}
+      size={size}
+      iconStyles={iconStyles}
+    />
+  );
+};
+```
+
+**In v11** you'd extend `systemIconStencil` to reuse its styles:
+
+```tsx
+// v11
+import {createStencil} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+import {systemIconStencil} from '@workday/canvas-kit-react/icon';
+
+const navIconStencil = createStencil({
+  // We extend `systemIconStencil` to inherit it's base styles, modifiers and variables so that we can customize it
+  extends: systemIconStencil,
+  vars: {
+    // These variables support our styling iconHover and iconBackgroundHover
+    // they can be removed later and overwritten by `cs`.
+    // Also note the variables have no value. This allows for cascading styles.
+    fillHover: '',
+    backgroundHover: '',
+  },
+  base: ({fillHover, backgroundHover}) => ({
+    display: 'inline-flex',
+    pointerEvents: 'unset',
+    // instead of using our old tokens it's better to use our new system tokens
+    margin: `${system.space.x1} ${system.space.x1} 0 0`,
+    padding: '0',
+    '&:hover, &.hover': {
+      // systemIconStencil doesn't have hover specific variables
+      // so we reassigned color and backgroundColor variables using pseudo-selector
+      [systemIconStencil.vars.color]: fillHover,
+      [systemIconStencil.vars.backgroundColor]: backgroundHover,
+    },
+  }),
+});
+
+// Your reusable NavIcon component using Stencils
+const NavIcon = ({
+  iconColor,
+  iconHover,
+  iconBackground,
+  iconBackgroundHover,
+  icon,
+  size,
+  ...elemProps
+}) => {
+  // insert icon function used by platform or any other functionality here
+
+  return (
+    <span
+      icon={icon}
+      {...handleCsProp(
+        elemProps,
+        navIconStencil({
+          // Because we're extending systemIconStencil, it already has a size prop and applies size to the svg's width and height
+          // so we don't need to set these variables in our navIconStencil
+          size,
+          // systemIconStencil already has color (for icon fill) and backgroundColor variables
+          // so we assigned them to our prop values
+          color: iconColor,
+          backgroundColor: iconBackground,
+          fillHover: iconHover,
+          backgroundHover: iconBackgroundHover,
+        })
+      )}
+    />
+  );
+};
+```
+
+Another example of Stencil extension and customization is our
+[CustomButton](https://workday.github.io/canvas-kit/?path=/story/components-buttons--custom-styles)
+example. This example highlights the power of inheritance that you get from extending stencils.

package/dist/mdx/styling/mdx/FromEmotion.mdx

@@ -0,0 +1,178 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+import EmotionButton from './examples/EmotionButton';
+import ManualStylesButton from './examples/ManualStylesButton';
+import StylingButton from './examples/StylingButton';
+
+
+# Converting from @emotion/styled
+
+The most difficult part of understanding styling without Emotion's runtime is the mindset shift. You
+are using CSS to merge properties instead of JavaScript. This is essential to remove the runtime of
+Emotion. We'll use a contrived button example using `@emotion/styled` and our styling solution to
+step through the differences.
+
+## Button using `@emotion/styled`
+
+<ExampleCodeBlock code={EmotionButton} />
+
+If we inspect each button, we'll notice each has a different class name. They all look like
+`css-{hash}`:
+
+For example, the Primary buttons:
+
+- Primary Large: `css-oqv33j`
+- Primary Medium: `css-1nhzlx`
+- Primary Small: `css-1ygk6q`
+
+This means each button is a unique style sheet insert by Emotion. If we render each permutation at
+once, there will only be one expensive
+[style recalculation](https://microsoftedge.github.io/DevTools/explainers/StyleTracing/explainer.html)
+
+Converting to use the Canvas Kit Styling solution means organizing a little different. In our
+example, it is already organized well, but conditionals might be anywhere in the style functions and
+will need to be organized in groups.
+
+## Button using only `createStyles`
+
+What are we really trying to accomplish? [BEM](https://getbem.com/introduction) fits well with
+compound components. BEM stands for Block, Element, Modifer. In compound components, "Block" refers
+to a container component while "Element" refers to subcomponets. The "Modifer" refers to changing
+the appearance of a block.
+
+In our example, all styles that are common to all appearances of our button. It might be
+`borderRadius`, `fontFamily`. We can use `createStyles` to define these styles:
+
+```ts
+const baseStyles = createStyles({
+  fontSize: '1rem',
+  display: 'flex',
+  borderRadius: '1rem',
+});
+```
+
+The `variant` modifiers use a variable prop called `backgroundColor` which cannot be variable at
+runtime. We need to use a CSS Variable for this.
+
+We can create modifers using `createStyles` and organize them in an object:
+
+```ts
+const modifierStyles = {
+  variant: {
+    primary: createStyles({
+      background: `var(--background-color-button, blue)`,
+      color: 'white',
+    }),
+    secondary: createStyles({
+      background: `var(--background-color-button, gray)`,
+    }),
+    danger: createStyles({
+      background: `var(--background-color-button, red)`,
+    }),
+  },
+  size: {
+    large: createStyles({
+      fontSize: '1.4rem',
+      height: '2rem',
+    }),
+    medium: createStyles({
+      fontSize: '1rem',
+      height: '1.5rem',
+    }),
+    small: createStyles({
+      fontSize: '0.8rem',
+      height: '1.2rem',
+    }),
+  },
+};
+```
+
+Each modifier value uses `createStyles` which returns a different class name. This means we can
+create a "Primary Large" button by applying these modifiers to the `className` prop of a React
+element:
+
+```jsx
+<button className={`${baseStyles} ${modifierStyles.variant.primary} ${modifierStyles.size.large}`}>
+  Primary Large
+</button>
+```
+
+This will create a button with 3 separate class names applied. `@emotion/styled` only applies a
+single css class name.
+
+```html
+<!-- @emotion/styled -->
+<button class="css-108wq52">Primary Large</button>
+
+<!-- createStyles -->
+<button class="css-puxv12 css-puxv13 css-puxv16">Primary Large</button>
+```
+
+If you want to change the background color, you'll have to pass it using `style`:
+
+```jsx
+<button
+  className={`${baseStyles} ${modifierStyles.size.large}`}
+  style={{'--color-background-button': 'orange'}}
+>
+  Orange Large
+</button>
+```
+
+The output HTML will look like:
+
+```html
+<button class="css-puxv12 css-puxv16" style="--color-background-button: orange;">
+  Orange Large
+</button>
+```
+
+This works because CSS Custom Properties cascade values. The `style` attribute defines styles on the
+element directly. This is a runtime in React that allows us to change a style without a new style
+block - the styles can be static, but we can still have variable property values.
+
+<ExampleCodeBlock code={ManualStylesButton} />
+
+## Button using all utilities
+
+If we want variables that are hashed and make it easier to define and use, we have `createVars`.
+There are also edge cases for modifiers like allowing `undefined`, so we made a `createModifiers`
+function as well. Both `createModifiers` and `createVars` return a function that makes it easier to
+call with inputs and will return the correct output.
+
+For example, `createModifiers`:
+
+```tsx
+const myModifiers = createModifiers({
+  size: {
+    large: 'button-large',
+    small: 'button-small'
+  }
+})
+
+myModifiers.size.large // 'button-large'
+
+// the function knows what config can be passed
+// and what restrictions each value has
+myModifiers({size: 'large'}) // 'button-large'
+myModifiers({size: 'small'}) // 'button-small'
+myModifiers() // ''
+
+// in a component
+<div className={myModifiers({size: 'large'})} /> // <div class="button-large" />
+```
+
+`createVars`:
+
+```tsx
+const myVars = createVars('background', 'color')
+
+myVars.color // something like `--color-{hash}`
+
+// the function knows what keys are allowed
+myVars({color: 'red'}) // {'--color-{hash}': 'red'}
+
+// in a component
+<div style={myVars({color: 'red'})} /> // <div style="--color-{hash}: red;">
+```
+
+<ExampleCodeBlock code={StylingButton} />

package/dist/mdx/styling/mdx/MergingStyles.mdx

@@ -0,0 +1,164 @@
+import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
+import {InformationHighlight} from '@workday/canvas-kit-preview-react/information-highlight';
+import {system} from '@workday/canvas-tokens-web';
+import StylingOverrides from './examples/StylingOverrides';
+
+
+# Merging Styles
+
+## mergeStyles
+
+In v9, we used `@emotion/styled` or `@emotion/react` for all styling which is a runtime styling
+solution. Starting in v10, we're migrating our styling to a more static solution using
+`createStyles` and the `cs` prop.
+
+For a transition period, we're opting for backwards compatibility. If style props are present,
+[styled components](https://emotion.sh/docs/styled) are used, or the
+[css prop](https://emotion.sh/docs/css-prop) is used in a component, Emotion's style merging will be
+invoked to make sure the following style precedence:
+
+```
+createStyles > CSS Prop > Styled Component > Style props
+```
+
+This will mean that any `css` prop or use of `styled` within the component tree _per element_ will
+cause style class merging. For example:
+
+```tsx
+import styled from '@emotion/styled';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {mergeStyles} from '@workday/canvas-kit-react/layout';
+
+const styles1 = createStyles({
+  padding: 4,
+});
+
+const styles2 = createStyles({
+  padding: 12,
+});
+
+const Component1 = props => {
+  return <div {...mergeStyles(props, [styles1])} />;
+};
+
+const Component2 = props => {
+  return <Component1 cs={styles2} />;
+};
+
+const Component3 = styled(Component1)({
+  padding: 8,
+});
+
+const Component4 = props => {
+  return <Component3 cs={styles2} />;
+};
+
+export default () => (
+  <>
+    <Component1 />
+    <Component2 />
+    <Component3 />
+    <Component4 />
+  </>
+);
+```
+
+The `styled` component API is forcing `mergeStyles` to go into Emotion merge mode, which removes the
+`style1` class name and creates a new class based on all the merged style properties. So
+`.component3` is a new class created by Emotion at render time that merges `.style1` and
+`{padding: 8px}`. `Component4` renders `Component3` with a `cs` prop, but `Component3` is already in
+merge mode and so `Component4` will also merge all styles into a new class name of `.component4`
+that has the styles from `.style1`, `.component3`, and `{padding: 12px}`:
+
+```html
+<head>
+  <style>
+    .styles1 {
+      padding: 4px;
+    }
+    .styles2 {
+      padding: 8px;
+    }
+    .component3 {
+      padding: 4px;
+      padding: 8px;
+    }
+    .component4 {
+      padding: 4px;
+      padding: 8px;
+      padding: 12px;
+    }
+  </style>
+</head>
+
+<div class="styles1"></div>
+<div class="styles1 styles2"></div>
+<div class="component3"></div>
+<div class="component4"></div>
+```
+
+The `css` prop and `styled` component APIs will rewrite the `className` React prop by iterating over
+all class names and seeing if any exist within the cache. If a class name does exist in the cache,
+the CSS properties are copied to a new style property map until all the class names are evaluated
+and removed from the `className` prop. Emotion will then combine all the CSS properties and inject a
+new `StyleSheet` with a new class name and add that class name to the element.
+
+The following example shows this style merging.
+
+<ExampleCodeBlock code={StylingOverrides} />
+
+CSS style property merging works by
+[CSS specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity). If two matching
+selectors have the same specificity, the last defined property wins. Stencils take advantage of this
+by making all styles have the same specificity of `0-1-0` and inserting `base` styles, then
+`modifiers` (in order), then `compound` modifiers (in order). This means if a property was defined
+in `base`, a `modifier`, and a `compound` modifier, the `compound` modifier would win because it is
+the last defined. This should be the expected order.
+
+<InformationHighlight className="sb-unstyled" variant="caution" cs={{marginBlock: system.space.x4}}>
+  <InformationHighlight.Icon />
+  <InformationHighlight.Heading>Caution</InformationHighlight.Heading>
+  <InformationHighlight.Body>
+    While we support `mergeStyles` we'd advise against using this in your components so that users
+    can get the performance benefit of static styling using utilities like `createStyles` and
+    `createStencil` in tandem with the `cs` prop.
+  </InformationHighlight.Body>
+</InformationHighlight>
+
+### mergeStyles API
+
+<SymbolDoc hideHeading name="mergeStyles" />
+
+## handleCsProp
+
+But what about when using components that use `@emotion/react` or `@emotion/styled`? Those libraries
+use a different approach. Instead of multiple class names, they use a single, merged class name.
+
+`handleCsProp` was created to handle integration with existing components that use the `css` prop
+from `@emotion/react` or the `styled` components from `@emotion/styled`. If a class name from one of
+those libraries is detected, style merging will follow the same rules as those libraries. Instead of
+multiple class names, a single class name with all matching properties is created. The
+`handleCsProp` also takes care of merging `style` props, `className` props, and can handle the `cs`
+prop:
+
+```tsx
+const myStencil = createStencil({
+  // ...
+});
+
+const MyComponent = elemProps => {
+  return <div {...handleProps(elemProps, myStencil({}))} />;
+};
+
+// All props will be merged for you
+<MyComponent style={{color: 'red'}} className="my-classname" cs={{position: 'relative'}} />;
+```
+
+`handleCsProp` will make sure the `style` prop is passed to the `div` and that the `my-classname`
+CSS class name appears on the `div`'s class list. Also the `cs` prop will add the appropriate styles
+to the element via a CSS class name. If your component needs to handle being passed a `className`,
+`style`, or `cs` prop, use `handleCsProp`.
+
+### handleCsProp API
+
+<SymbolDoc hideHeading name="handleCsProp" />