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

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>

package/dist/mdx/styling/mdx/Stencils.mdx

@@ -0,0 +1,459 @@
+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 CreateStencil from './examples/CreateStencil';
+
+
+# Stencils
+
+Stencils are a reusable function that returns `style` and `className` props in an object. A Stencil
+should apply to a single element. If your component has nested elements, you can youse `parts` to
+targer those elements in the Stencil. If your component is a compound component, a stencil should be
+created for each subcomponent. If your component is a config component, a stencil can have nested
+styles.
+
+We created Stencils as the reusable primitive of components. Stencils provide:
+
+- `vars`: CSS variables for dynamic properties
+- `base`: base styles to any component
+- `modifier`: modifiers like “size = small,medium,large” or “color=red,blue,etc”
+- `parts`: matching sub-elements that are part of a component
+- `compound`: compound modifiers - styles that match multiple modifiers
+
+## Basic Example
+In the example below, Stencils allow you to dynamically style elements or components based on properties.
+
+<ExampleCodeBlock code={CreateStencil} />
+
+## When to Use `createStencil`
+- When you're styling parts of a component that rely on dynamic properties.
+- When you want to create a reusable component with dynamic styles.
+
+
+Use a Stencil when building reusable components that have dynamic styles and properties.
+
+## Concepts
+
+### Base styles
+
+Base styles are always applied to a Stencil. All your default styles should go here. Base styles
+support psuedo selectors like `:focus-visible` or `:hover` as well as child selectors. Any selector
+supported by `@emotion/css` is valid here. All styles must be static and statically analyzable by
+the tranformer. If you need dynamic styling, look at Variables and Modifiers.
+
+### Variables
+
+Variables allow some properties to be dynamic. They work by creating
+[CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) with
+unique names and are applied using the
+[style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) property of an element
+to locally scope an override. Since we don't have access to those names, we need a function wrapper
+around our style objects. This includes `base`, `modifiers`, and `compound` modifiers.
+
+Here's a simplified example:
+
+```tsx
+const myStencil = createStencil({
+  vars: {
+    defaultColor: 'red' // default value
+    nonDefaultedColor: '', // will allow for uninitialization
+  },
+  base: ({defaultColor}) => {
+    color: defaultColor // `defaultColor` is '--defaultColor-abc123', not 'red'
+  }
+})
+
+const elemProps = myStencil({color: 'blue'}) // {style: {'--defaultColor-abc123': 'blue'}}
+
+<div {...elemProps} />
+```
+
+This will produce the following HTML:
+
+```html
+<style>
+  .css-abc123 {
+    --defaultColor-abc123: red;
+    color: var(--defaultColor-abc123);
+  }
+</style>
+<div class="css-123abc" style="--defaultColor-abc123: blue;"></div>
+```
+
+The element will have a `color` property of `'blue'` because the element style is the highest
+specificity and wins over a local class name. In the "Styles" tab of developer tools, it will look
+like the following:
+
+```
+element.style {
+  --defaultColor-abc123: blue;
+}
+
+.css-abc123 {
+  --defaultColor-abc123: red;
+  color: var(--defaultColor-abc123); // blue
+}
+```
+
+Variables are automatically added to the config of a Stencil. They share the same namespace as
+modifiers, so **do not have a modifier with the same name as a variable**.
+
+<InformationHighlight className="sb-unstyled" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading>Note</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		Variables should be used sparingly. Style properties can be easily overridden without
+variables. Variables are useful if you want to expose changing properties regardless of selectors.
+For example, Buttons use variables for colors of all states (hover, active, focus, disabled, and
+nested icons). Without variables, overriding the focus color would require deeply nested selector
+overrides.
+	</InformationHighlight.Body>
+</InformationHighlight>
+
+#### Cascading Variables
+
+Notice the `nonDefaultedColor` is not included in the base styles like `defaultColor` was. If a
+variable has an empty string, it will can be uninitialized. Stencil variables with a default value
+will create a "cascade barrier". A cascade barrier prevents the variable from "leaking" into the
+component. For example, if a `Card` component was rendered within another `Card` component, the
+variables from the parent `Card` would not leak into the child `Card` component. But there are times
+where a component expects a parent component to set a CSS variable and that it should cascade to the
+component. An example of this is the relationship between `SystemIcon` and `Button`. The `Button`
+components set the `SystemIcon` variables and they should cascade into the `SystemIcon` component.
+
+<InformationHighlight className="sb-unstyled" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading>Note</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		Non-cascade variables _could_ be initialized. If you use uninitialized variables, be sure
+to use a fallback in your styles.
+	</InformationHighlight.Body>
+</InformationHighlight>
+
+```tsx
+const myStencil = createStencil({
+  vars: {
+    color: '', // uninitialized
+  },
+  base({color}) {
+    return {
+      // provide a fallback. A uninitialized CSS variable will fall back to `initial`.
+      // for the `color` CSS property, that's most likely black (default text color)
+      color: cssVar(color, 'red'),
+    };
+  },
+});
+```
+
+#### Nested Variables
+
+Variables can be nested one level. This can be useful for colors with different psuedo selectors
+like `:hover` or `:focus`. Here's an example:
+
+```tsx
+const myStencil = createStencil({
+  vars: {
+    default: {
+      color: 'red'
+    },
+    hover: {
+      color: 'blue'
+    },
+    focus: {
+      color: 'orange'
+    }
+  },
+  base: ({default, hover, focus}) => {
+    color: default.color,
+    '&:hover': {
+      color: hover.color
+    },
+    '&:focus': {
+      color: focus.color
+    }
+  }
+})
+```
+
+### Modifiers
+
+Modifiers are modifications to base styles. It should be used to change the appearance of a base
+style. For example, a button may have a modifier for "primary" or "secondary" which may change the
+visual emphasis of the button. Each modifier has its own CSS class name and the stencil will return
+the correct CSS classes to apply to an element based on what modifiers are active.
+
+```tsx
+const buttonStencil = createStencil({
+  base: {
+    padding: 5
+    // base styles
+  },
+  modifiers: {
+    variant: { // modifier name
+      primary: {
+        background: 'blue'
+      },
+      secondary: {
+        background: 'gray'
+      }
+    }
+  },
+  defaultModifiers: {
+    variant: 'secondary'
+  }
+})
+
+const elemProps = myStencil({variant: 'primary'}) // {className: "css-a0 css-a1"}
+
+<div {...elemProps} />
+```
+
+The HTML may look something like this:
+
+```html
+<style>
+  .css-a0 {
+    padding: 5px;
+  }
+  .css-a1 {
+    background: 'blue';
+  }
+  .css-a2 {
+    background: 'gray';
+  }
+</style>
+<div class="css-a0 css-a1"></div>
+```
+
+The optional `defaultModifiers` config property will default modifiers to a value. If a modifier is
+not passed to the stencil, the default will be used.
+
+```tsx
+myStencil(); // className will be `'css-a0 css-a2'`
+```
+
+### Compound Modifiers
+
+A compound modifier creates a new CSS class for the intersection of two or more modifiers. Each
+modifier can have its own separate CSS class while the intersection is a different CSS class.
+
+For example:
+
+```tsx
+const buttonStencil = createStencil({
+  base: {
+    padding: 10,
+    // base styles
+  },
+  modifiers: {
+    size: {
+      // modifier name
+      large: {
+        padding: 20,
+      },
+      small: {
+        padding: 5,
+      },
+    },
+    iconPosition: {
+      start: {
+        paddingInlineStart: 5,
+      },
+      end: {
+        paddingInlineEnd: 5,
+      },
+    },
+  },
+  compound: [
+    {
+      modifiers: {size: 'large', position: 'start'},
+      styles: {
+        paddingInlineStart: 15,
+      },
+    },
+    {
+      modifiers: {size: 'small', position: 'end'},
+      styles: {
+        paddingInlineEnd: 0,
+      },
+    },
+  ],
+});
+
+<div {...buttonStencil()} />
+<div {...buttonStencil({size: 'small'})} />
+<div {...buttonStencil({size: 'small', iconPosition: 'end'})} />
+```
+
+The HTML will look something like this:
+
+```html
+<style>
+  .a0 {
+    padding: 10px;
+  }
+  .a1 {
+    padding: 20px;
+  }
+  .a2 {
+    padding: 5px;
+  }
+  .a3 {
+    padding-inline-start: 5px;
+  }
+  .a4 {
+    padding-inline-end: 5px;
+  }
+  .a5 {
+    padding-inline-start: 15px;
+  }
+  .a6 {
+    padding-inline-start: 0px;
+  }
+</style>
+<div class="a0"></div>
+<div class="a0 a2"></div>
+<div class="a0 a2 a4 a6"></div>
+```
+
+Notice the stencil adds all the class names that match the base, modifiers, and compound modifiers.
+
+### Variables and Modifiers with same keys
+
+It is possible to have a variable and modifier sharing the same key. The Stencil will accept either
+the modifier option or a string. The value will be sent as a variable regardless while the modifer
+will only match if it is a valid modifer key.
+
+```tsx
+const buttonStencil = createStencil({
+  vars: {
+    width: '10px',
+  },
+  base({width}) {
+    return {
+      width: width,
+    };
+  },
+  modifiers: {
+    width: {
+      zero: {
+        width: '0', // overrides base styles
+      },
+    },
+  },
+});
+
+// `'zero'` is part of autocomplete
+myStencil({width: 'zero'});
+// returns {className: 'css-button css-button--width-zero', styles: { '--button-width': 'zero'}}
+
+// width also accepts a string
+myStencil({width: '10px'});
+// returns {className: 'css-button', styles: { '--button-width': '10px'}}
+```
+
+## Styling Elements via Component Parts
+
+The goal of compound components is to expose one component per semantic element. Most of the time
+this means a 1:1 relationship of a component and DOM element. Sometimes a semantic element contains
+non-semantic elements for styling. An example might be a `<button>` with a icon for visual
+reinforcement, and a label for a semantic label. The semantic element is the `<button>` while the
+icon has no semantic value and the label automatically provides the semantic button with an
+accessible name. In order to style the icon and label elements, you have to know the DOM structure
+to target those specific elements in order to style it.
+
+```jsx
+import {createStencil} from '@workday/canvas-kit-styling';
+
+const myButtonStencil = createStencil({
+  base: {
+    background: 'transparent',
+    i: {
+      // ...icon styles
+    },
+    span: {
+      // ...label styles
+    },
+    ':hover': {
+      // ...hover button styles
+      i: {
+        // ...hover icon styles
+      },
+      span: {
+        // ...hover label styles
+      },
+    },
+  },
+});
+
+const MyButton = ({children, ...elemProps}) => {
+  return (
+    <button {...handleCsProp(elemProps, myButtonStencil())}>
+      <i />
+      <span>{children}</span>
+    </button>
+  );
+};
+```
+
+### Using Component Parts to Style Elements
+
+To style elements in the render function, we'll need to choose what elements to add the parts to. In
+the example below, we're able to spread the parts directly to elements. The Stencil will generate
+the type and value most appropriate for the context the part is used. In the Stencil, the part is
+represented by a string that looks like `[data-part="{partValue}"]` and in the render function, it
+is an object that looks like `{'data-part': partValue}`.
+
+```jsx
+import {createStencil, handleCsProp} from '@workday/canvas-kit-styling';
+
+const myButtonStencil = createStencil({
+  parts: {
+    icon: 'my-button-icon',
+    label: 'my-button-label',
+  },
+  base: ({iconPart, labelPart}) => ({
+    background: 'transparent',
+    [iconPart]: {
+      // `[data-part="my-button-icon"]`
+      // ...icon styles
+    },
+    [labelPart]: {
+      // `[data-part="my-button-label"]`
+      // ...label styles
+    },
+    '&:hover': {
+      // ...hover styles for button element
+      [iconPart]: {
+        // ...hover styles for icon part
+      },
+    },
+  }),
+});
+
+const MyButton = ({children, ...elemProps}) => {
+  return (
+    <button {...handleCsProp(elemProps, myButtonStencil())}>
+      <i {...myButtonStencil.parts.icon} /> {/* data-part={my-button-icon} */}
+      <span {...myButtonStencil.parts.label}>{children}</span> {/* data-part={my-button-label} */}
+    </button>
+  );
+};
+```
+
+As a reusable component, you can use component parts to style elements that are not exposed in the
+API. Consumers can also use the type safe Stencil to target that element to style it as well. As a
+general rule, a Stencil maps to a component. Multiple Stencils per component usually means nested
+elements that are not targets for style overrides.
+
+<InformationHighlight className="sb-unstyled" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading>Note</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		While component parts are a way to give access to elements in order to style, they
+ should be used sparingly. Using component parts increases CSS specificity. A component part should
+ not be used on a nested component that has its own Stencil. The result will be any style
+ properties defined with a component part will have a higher specificity than other styles.
+	</InformationHighlight.Body>
+</InformationHighlight>