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

package/dist/mdx/styling/mdx/Utilities.mdx

@@ -0,0 +1,246 @@
+import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
+import CreateStyles from './examples/CreateStyles';
+import CreateVars from './examples/CreateVars';
+
+
+# Canvas Kit Styling Utilities
+
+A collection of helpful functions for styling with `@workday/canvas-kit-styling`. While they're
+fairly simple, they make styling much nicer.
+
+## Pixels to Rem
+
+This function converts a `px` value (number) to `rem` (string). This keeps you from having to do any
+tricky mental division or write irrational numbers.
+
+```ts
+import {px2rem} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  // returns '0.0625rem'
+  margin: px2rem(1),
+};
+```
+
+## Calc Functions
+
+Calc functions are useful for doing basic math operations with CSS `calc()` and variables. They will
+also wrap variables automatically in `var()`.
+
+### Add
+
+This function returns a CSS `calc()` addition string.
+
+```ts
+import {calc} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  // returns 'calc(var(--cnvs-sys-space-x1) + 0.125rem)'
+  padding: calc.add(system.space.x1, '0.125rem'),
+};
+```
+
+### Subtract
+
+This function returns a CSS `calc()` subtraction string.
+
+```ts
+import {calc} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  // returns 'calc(var(--cnvs-sys-space-x1) - 0.125rem)'
+  padding: calc.subtract(system.space.x1, '0.125rem'),
+};
+```
+
+### Multiply
+
+This function returns a CSS `calc()` multiplication string.
+
+```ts
+import {calc} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  // returns 'calc(var(--cnvs-sys-space-x1) * 3)'
+  padding: calc.multiply(system.space.x1, 3),
+};
+```
+
+### Divide
+
+This function returns a CSS `calc()` division string
+
+```ts
+import {calc} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  // returns 'calc(var(--cnvs-sys-space-x1) / 2)'
+  padding: calc.divide(system.space.x1, 2),
+};
+```
+
+### Negate
+
+This function negates a CSS variable to give you the opposite value. This keeps you from having to
+wrap the variable in `calc()` and multiplying by `-1`.
+
+```ts
+import {calc} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  // returns 'calc(var(--cnvs-sys-space-x4) * -1)'
+  margin: calc.negate(system.space.x4),
+};
+```
+
+## keyframes
+
+The `keyframes` function re-exports the [Emotion CSS keyframes](https://emotion.sh/docs/keyframes)
+function, but is compatible with a custom Emotion instance and is understood by the Static style
+transformer.
+
+### Usage Example
+
+```tsx
+import {system} from '@workday/canvas-tokens-web';
+import {createComponent} from '@workday/canvas-kit-react/common';
+import {
+  handleCsProp,
+  keyframes,
+  createStencil,
+  calc,
+  px2rem,
+  CSProps,
+} from '@workday/canvas-kit-styling';
+
+/**
+ * Keyframe for the dots loading animation.
+ */
+const keyframesLoading = keyframes({
+  '0%, 80%, 100%': {
+    transform: 'scale(0)',
+  },
+  '40%': {
+    transform: 'scale(1)',
+  },
+});
+
+export const loadingStencil = createStencil({
+  base: {
+    display: 'inline-flex',
+    gap: system.space.x2,
+    width: system.space.x4,
+    height: system.space.x4,
+    fontSize: system.space.zero,
+    borderRadius: system.shape.round,
+    backgroundColor: system.color.bg.muted.softer,
+    outline: `${px2rem(2)} solid transparent`,
+    transform: 'scale(0)',
+    animationName: keyframesLoading,
+    animationDuration: calc.multiply('150ms', 35),
+    animationIterationCount: 'infinite',
+    animationTimingFunction: 'ease-in-out',
+    animationFillMode: 'both',
+  },
+});
+
+/**
+ * A simple component that displays three horizontal dots, to be used when some data is loading.
+ */
+export const LoadingDot = createComponent('div')({
+  displayName: 'LoadingDots',
+  Component: ({...elemProps}: CSProps, ref, Element) => {
+    return <Element ref={ref} {...handleCsProp(elemProps, loadingStencil())}></Element>;
+  },
+});
+```
+
+## injectGlobal
+
+The `injectGlobal` function re-exports the
+[Emotion CSS injectGlobal](https://emotion.sh/docs/@emotion/css#global-styles) function, but is
+compatible with a custom Emotion instance and is understood by the Static style transformer.
+
+### Usage Example
+
+```tsx
+import {createRoot} from 'react-dom/client';
+import {fonts} from '@workday/canvas-kit-react-fonts';
+import {system} from '@workday/canvas-tokens-web';
+import {cssVar, injectGlobal} from '@workday/canvas-kit-styling';
+import {App} from './App';
+
+import '@workday/canvas-tokens-web/css/base/_variables.css';
+import '@workday/canvas-tokens-web/css/brand/_variables.css';
+import '@workday/canvas-tokens-web/css/system/_variables.css';
+
+//@ts-ignore
+injectGlobal({
+  ...fonts,
+  'html, body': {
+    fontFamily: cssVar(system.fontFamily.default),
+    margin: 0,
+    minHeight: '100vh',
+  },
+  '#root, #root < div': {
+    minHeight: '100vh',
+    ...system.type.body.small,
+  },
+});
+
+const container = document.getElementById('root')!;
+const root = createRoot(container);
+root.render(<App />);
+```
+
+## Custom Emotion Instance
+
+Static style injection happens during the parsing stages of the files. This means when you `import`
+a component that uses static styling, the styles are injected immediately. This happens way before
+rendering, so using the Emotion [CacheProvider](https://emotion.sh/docs/cache-provider) does not
+work. A custom instance must be created _before_ any style utilities are called - during the
+bootstrapping phase of an application. We don't have a working example because it requires an
+isolated application, but here's an example adding a `nonce` to an application:
+
+```tsx
+// bootstrap-styles.ts
+import {createInstance} from '@workday/canvas-kit-styling';
+
+// assuming this file is being called via a `script` tag and that
+// script tag has a `nonce` attribute set from the server
+createInstance({nonce: document.currentScript.nonce});
+
+// index.ts
+import React from 'react';
+import ReactDOM from 'react-dom';
+
+// call the bootstrap in the import list. This has the side-effect
+// of creating an instance
+import './bootstrap-styles';
+
+import App from './App';
+
+const root = ReactDOM.createRoot(document.querySelector('#root'));
+
+root.render(<App />);
+
+// App.tsx
+import React from 'react';
+
+// The following will create and inject styles. We cannot adjust
+// the Emotion instance after this import
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+// if we call `createInstance` here, we'll get a warning in
+// development mode
+
+export default () => {
+  return <PrimaryButton>Button</PrimaryButton>;
+};
+```

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>
+);