@workday/canvas-kit-docs 13.1.4 → 13.1.6

package/dist/es6/lib/docs.js

@@ -338465,6 +338465,186 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
       ]
     }
   },
+  {
+    "name": "useTabOverflowScroll",
+    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsList.tsx",
+    "description": "",
+    "declarations": [
+      {
+        "name": "useTabOverflowScroll",
+        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsList.tsx"
+      }
+    ],
+    "tags": {},
+    "type": {
+      "kind": "function",
+      "name": {
+        "kind": "symbol",
+        "name": "createElemPropsHook"
+      },
+      "parameters": [
+        {
+          "kind": "parameter",
+          "name": "model",
+          "description": "",
+          "tags": {},
+          "declarations": [],
+          "type": {
+            "kind": "symbol",
+            "name": "TabsModel"
+          },
+          "required": true
+        },
+        {
+          "kind": "parameter",
+          "name": "elemProps",
+          "description": "",
+          "tags": {},
+          "declarations": [],
+          "type": {
+            "kind": "object",
+            "properties": [
+              {
+                "kind": "property",
+                "name": "aria-orientation",
+                "required": false,
+                "type": {
+                  "kind": "union",
+                  "value": [
+                    {
+                      "kind": "string",
+                      "value": "vertical"
+                    },
+                    {
+                      "kind": "string",
+                      "value": "horizontal"
+                    }
+                  ]
+                },
+                "description": "",
+                "declarations": [
+                  {
+                    "name": "aria-orientation",
+                    "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsList.tsx"
+                  }
+                ],
+                "tags": {}
+              }
+            ]
+          },
+          "required": false
+        },
+        {
+          "kind": "parameter",
+          "name": "ref",
+          "description": "",
+          "tags": {},
+          "declarations": [],
+          "type": {
+            "kind": "external",
+            "name": "React.Ref",
+            "url": "https://reactjs.org/docs/refs-and-the-dom.html"
+          },
+          "required": false
+        }
+      ],
+      "returnType": {
+        "kind": "object",
+        "properties": [
+          {
+            "kind": "property",
+            "name": "ref",
+            "required": true,
+            "type": {
+              "kind": "function",
+              "parameters": [
+                {
+                  "kind": "parameter",
+                  "name": "instance",
+                  "type": {
+                    "kind": "union",
+                    "value": [
+                      {
+                        "kind": "symbol",
+                        "name": "T",
+                        "value": "T"
+                      },
+                      {
+                        "kind": "primitive",
+                        "value": "null"
+                      }
+                    ]
+                  },
+                  "required": true,
+                  "rest": false,
+                  "description": "",
+                  "declarations": [
+                    {
+                      "name": "instance",
+                      "filePath": "/home/runner/work/canvas-kit/canvas-kit/node_modules/@types/react/ts5.0/index.d.ts"
+                    }
+                  ],
+                  "tags": {}
+                }
+              ],
+              "members": [],
+              "returnType": {
+                "kind": "primitive",
+                "value": "void"
+              }
+            },
+            "description": "",
+            "tags": {},
+            "declarations": []
+          },
+          {
+            "kind": "property",
+            "name": "onScroll",
+            "required": true,
+            "type": {
+              "kind": "function",
+              "parameters": [
+                {
+                  "kind": "parameter",
+                  "name": "event",
+                  "type": {
+                    "kind": "symbol",
+                    "name": "React.UIEvent",
+                    "typeParameters": [
+                      {
+                        "kind": "symbol",
+                        "name": "HTMLDivElement",
+                        "value": "HTMLDivElement"
+                      }
+                    ],
+                    "value": "UIEvent<T, E>"
+                  },
+                  "required": true,
+                  "rest": false,
+                  "description": "",
+                  "declarations": [
+                    {
+                      "name": "event",
+                      "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsList.tsx"
+                    }
+                  ],
+                  "tags": {}
+                }
+              ],
+              "members": [],
+              "returnType": {
+                "kind": "primitive",
+                "value": "void"
+              }
+            },
+            "description": "",
+            "tags": {},
+            "declarations": []
+          }
+        ]
+      }
+    }
+  },
   {
     "name": "useTabsList",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsList.tsx",
@@ -338483,6 +338663,12 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
         "name": "composeHooks"
       },
       "parameters": [
+        {
+          "kind": "symbol",
+          "name": "useTabOverflowScroll",
+          "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsList.tsx",
+          "value": "useTabOverflowScroll"
+        },
         {
           "kind": "function",
           "name": {
@@ -338545,20 +338731,12 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               },
               {
                 "kind": "property",
-                "name": "overflowX",
+                "name": "aria-orientation",
                 "required": true,
                 "type": {
-                  "kind": "union",
-                  "value": [
-                    {
-                      "kind": "string",
-                      "value": "auto"
-                    },
-                    {
-                      "kind": "primitive",
-                      "value": "undefined"
-                    }
-                  ]
+                  "kind": "symbol",
+                  "name": "Orientation",
+                  "value": "any"
                 },
                 "description": "",
                 "tags": {},
@@ -339503,85 +339681,6 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
       "model": "TabsModel"
     }
   },
-  {
-    "name": "useTouchDirection",
-    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsList.tsx",
-    "description": "",
-    "declarations": [
-      {
-        "name": "useTouchDirection",
-        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsList.tsx"
-      }
-    ],
-    "tags": {},
-    "type": {
-      "kind": "function",
-      "parameters": [],
-      "members": [],
-      "returnType": {
-        "kind": "object",
-        "properties": [
-          {
-            "kind": "property",
-            "name": "direction",
-            "defaultValue": {
-              "kind": "unknown",
-              "value": "unknown",
-              "text": "touchDir"
-            },
-            "type": {
-              "kind": "union",
-              "value": [
-                {
-                  "kind": "string",
-                  "value": "left"
-                },
-                {
-                  "kind": "string",
-                  "value": "right"
-                },
-                {
-                  "kind": "primitive",
-                  "value": "undefined"
-                }
-              ]
-            },
-            "required": false,
-            "description": "",
-            "declarations": [
-              {
-                "name": "direction",
-                "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsList.tsx"
-              }
-            ],
-            "tags": {}
-          },
-          {
-            "kind": "property",
-            "name": "isDragging",
-            "defaultValue": {
-              "kind": "unknown",
-              "value": "unknown",
-              "text": "isDragging"
-            },
-            "type": {
-              "kind": "primitive",
-              "value": "boolean"
-            },
-            "required": true,
-            "description": "",
-            "declarations": [
-              {
-                "name": "isDragging",
-                "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsList.tsx"
-              }
-            ],
-            "tags": {}
-          }
-        ]
-      }
-    }
-  },
   {
     "name": "MenuPopperProps",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tabs/lib/TabsMenuPopper.tsx",

package/dist/es6/lib/stackblitzFiles/packageJSONFile.js

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "13.1.4",
-    "@workday/canvas-kit-preview-react": "13.1.4",
-    "@workday/canvas-kit-react": "13.1.4",
-    "@workday/canvas-kit-react-fonts": "^13.1.4",
-    "@workday/canvas-kit-styling": "13.1.4",
+    "@workday/canvas-kit-labs-react": "13.1.6",
+    "@workday/canvas-kit-preview-react": "13.1.6",
+    "@workday/canvas-kit-react": "13.1.6",
+    "@workday/canvas-kit-react-fonts": "^13.1.6",
+    "@workday/canvas-kit-styling": "13.1.6",
     "@workday/canvas-system-icons-web": "3.0.22",
     "@workday/canvas-tokens-web": "2.0.0"
   },

package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "13.1.4",
-    "@workday/canvas-kit-preview-react": "13.1.4",
-    "@workday/canvas-kit-react": "13.1.4",
-    "@workday/canvas-kit-react-fonts": "^13.1.4",
-    "@workday/canvas-kit-styling": "13.1.4",
+    "@workday/canvas-kit-labs-react": "13.1.6",
+    "@workday/canvas-kit-preview-react": "13.1.6",
+    "@workday/canvas-kit-react": "13.1.6",
+    "@workday/canvas-kit-react-fonts": "^13.1.6",
+    "@workday/canvas-kit-styling": "13.1.6",
     "@workday/canvas-system-icons-web": "3.0.22",
     "@workday/canvas-tokens-web": "2.0.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.