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

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" />

package/dist/mdx/styling/mdx/Overview.mdx

@@ -0,0 +1,254 @@
+import {InformationHighlight} from '@workday/canvas-kit-preview-react/information-highlight';
+import {Hyperlink} from '@workday/canvas-kit-react/button';
+import {system} from '@workday/canvas-tokens-web'
+
+
+# Canvas Kit Styling
+
+## Introduction
+
+Canvas Kit styling is a custom CSS-in-JS solution that provides both a runtime for development and a
+static parsing process for build time. This system offers several key benefits:
+
+- TypeScript autocomplete for enhanced developer experience
+- Low runtime overhead for better performance
+- Static CSS compilation for optimized builds
+- Dynamic styling with CSS Variables for flexible design
+
+The motivation behind this custom styling solution stems from the need to move beyond IE11 support
+and implement performance improvements using static styling methods. For more details, refer to the
+[Why Canvas Kit Styling](https://workday.github.io/canvas-kit/?path=/docs/styling-why-canvas-styling--docs)
+section.
+
+## Overview
+
+The Canvas Kit styling system consists of two main packages:
+
+- `@workday/canvas-kit-styling` - Core styling utilities for runtime use
+- `@workday/canvas-kit-styling-transform` - Build-time optimization tools
+
+These packages work together to provide a CSS-in-JS experience during development while enabling optimized static CSS in production.
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-styling
+```
+
+## Usage
+
+```tsx
+import React from 'react';
+import {createRoot} from 'react-dom/client';
+
+import {createStyles} from '@workday/canvas-kit-styling';
+
+const myStyles = createStyles({
+  backgroundColor: 'red',
+}); // returns the CSS class name created for this style
+
+myStyles; // something like "css-{hash}"
+
+const domNode = document.getElementById('root');
+const root = createRoot(domNode);
+
+root.render(<div className={myStyles}>Hello!</div>);
+```
+
+## Development
+
+Canvas Kit Styling comes with a runtime that doesn't need anything special for developement. The
+runtime uses `@emotion/css` to include your styles on the page.
+
+## Production
+
+If you wish to use the static compilation, you must use the `@workday/canvas-kit-styling-transform`
+package. Add the following to your project's `tsconfig.json` file:
+
+```json
+{
+  "compilerOptions": {
+    // other options
+    "plugins": [
+      {
+        "transform": "@workday/canvas-kit-styling-transform",
+        "prefix": "css",
+        "fallbackFiles": [""]
+      }
+    ]
+  }
+}
+```
+
+This adds a list of plugins to use when transforming TypeScript files into JavaScript files. The
+[ts-patch](https://www.npmjs.com/package/ts-patch) projects uses the `plugins` when running
+transforms.
+
+### Webpack
+
+You will need to transform TypeScript files using the `ts-patch` which is the same as the TypeScript
+tanspiler except it uses TypeScript's
+[transform API](https://levelup.gitconnected.com/writing-a-custom-typescript-ast-transformer-731e2b0b66e6)
+to transform code during compilation.
+
+In your webpack config, you add the following:
+
+```js
+{
+  rules: [
+    //...
+    {
+      test: /.\.tsx?$/,
+      loaders: [
+        // ts-loader
+        {
+          loader: require.resolve('ts-loader'),
+          options: {
+            compiler: 'ts-patch/compiler',
+          },
+        },
+        // OR awesome-typescript-loader
+        {
+          loader: require.resolve('awesome-typescript-loader'),
+        },
+      ],
+    },
+  ];
+}
+```
+
+## Core Styling Approaches for Static Styling
+For proper static styling there's two methods that you can use to apply styles.
+1. Using `createStyles` for simple object base styles.
+2. Using `createStencil` for dynamic styles and reusable components.
+
+Both approaches are intended to be used in tandem with the `cs` prop when applying styles to our components.
+
+### `cs` Prop
+
+The `cs` prop takes in a single, or an array of values that are created by the `cs` function, a
+string representing a CSS class name, or the return of the `createVars` function. It merges
+everything together and applies `className` and `style` attributes to a React element. Most of our
+components extend the `cs` prop so that you can statically apply styles to them.
+
+> **Important**: While the `cs` prop accepts a style object, **this will not** be considered
+> statically styling an element and you will lose the performance benefits. We plan on providing a babel plugin to extract these styles statically in a future version.
+
+```tsx
+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>;
+}
+```
+
+### `createStyles`
+
+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.
+
+```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>;
+}
+```
+
+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 className="sb-unstyled" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading>Information</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		For a more in depth overview, please view our <Hyperlink src="https://workday.github.io/canvas-kit/?path=/docs/styling-getting-started-create-styles--docs">Create Styles</Hyperlink> docs.
+	</InformationHighlight.Body>
+</InformationHighlight>
+
+### `createStencil`
+
+`createStencil` is a function for creating reusable, complex component styling systems. It manages
+`base` styles, `parts`, `modifiers`, `variables`, and `compound` modifiers. Most of our components
+also export their own Stencil that might expose CSS variables in order to modify the component.
+
+In the example below, we leverage `parts`, `vars`, `base` and `modifiers` to create a reusable
+`Card` component. The Stencil allows us to dynamic style the component based on the props.
+
+```tsx
+import {createStencil}from '@workday/canvas-kit-styling';
+import {Card} from '@workday/canvas-kit-react/card';
+import {system} from '@workday/canvas-tokens-webs';
+
+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'
+  },
+  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}) => ({
+        backgroundColor: system.color.bg.contrast.default,
+        color: system.color.text.inverse
+        [headerPart]: {
+          color: system.color.text.inverse
+        }
+      })
+    }
+  }
+})
+
+const ThemedCard = ({isDarkTheme, headerColor, elemProps}) => {
+  return (
+    /* Use the `cs` prop to apply the stencil and pass it the dynamic properties it needs to style accordingly */
+    <Card cs={themedCardStencil({isDarkTheme, headerColor})} {...elemProps}>
+	/* Apply the data part selector to the header */
+      <Card.Heading {...themedCardStencil.parts.header}>Canvas Supreme</Card.Heading>
+      <Card.Body>
+        Our house special supreme pizza includes pepperoni, sausage, bell peppers, mushrooms,
+        onions, and oregano.
+      </Card.Body>
+    </Card>
+  );
+};
+```
+
+<InformationHighlight className="sb-unstyled" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading>Information</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		For a more in depth overview, please view our <Hyperlink src="https://workday.github.io/canvas-kit/?path=/docs/styling-getting-started-stencils--docs">Create Stencil</Hyperlink> docs.
+	</InformationHighlight.Body>
+</InformationHighlight>