@workday/canvas-kit-docs 14.0.0-alpha.1165-next.0 → 14.0.0-alpha.1167-next.0

package/dist/es6/lib/docs.js

@@ -411376,12 +411376,12 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
   },
   {
     "name": "createConfig",
-    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/index.d.ts",
+    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/index.ts",
     "description": "",
     "declarations": [
       {
         "name": "createConfig",
-        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/index.d.ts"
+        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/index.ts"
       }
     ],
     "tags": {},
@@ -411402,7 +411402,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
           "declarations": [
             {
               "name": "config",
-              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/index.d.ts"
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/index.ts"
             }
           ],
           "tags": {}
@@ -411500,6 +411500,214 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
       }
     }
   },
+  {
+    "name": "getTSConfigFile",
+    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts",
+    "description": "Get the contents of the tsconfig in the system",
+    "declarations": [
+      {
+        "name": "getTSConfigFile",
+        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts"
+      }
+    ],
+    "tags": {},
+    "type": {
+      "kind": "function",
+      "parameters": [
+        {
+          "kind": "parameter",
+          "name": "tsconfigPath",
+          "type": {
+            "kind": "primitive",
+            "value": "string"
+          },
+          "required": true,
+          "rest": false,
+          "description": "",
+          "declarations": [
+            {
+              "name": "tsconfigPath",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts"
+            }
+          ],
+          "tags": {}
+        }
+      ],
+      "members": [],
+      "returnType": {
+        "kind": "symbol",
+        "name": "ParsedCommandLine",
+        "value": "ParsedCommandLine"
+      }
+    }
+  },
+  {
+    "name": "getCompilerOptions",
+    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts",
+    "description": "",
+    "declarations": [
+      {
+        "name": "getCompilerOptions",
+        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts"
+      }
+    ],
+    "tags": {},
+    "type": {
+      "kind": "function",
+      "parameters": [
+        {
+          "kind": "parameter",
+          "name": "tsconfigPath",
+          "type": {
+            "kind": "primitive",
+            "value": "string"
+          },
+          "required": true,
+          "rest": false,
+          "description": "",
+          "declarations": [
+            {
+              "name": "tsconfigPath",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts"
+            }
+          ],
+          "tags": {}
+        }
+      ],
+      "members": [],
+      "returnType": {
+        "kind": "symbol",
+        "name": "CompilerOptions",
+        "value": "CompilerOptions"
+      }
+    }
+  },
+  {
+    "name": "startWatch",
+    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts",
+    "description": "Create a watch program for TypeScript with transformers. It watches the specified\ntsconfigPath for changes and updates the program when changes are detected.",
+    "declarations": [
+      {
+        "name": "startWatch",
+        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts"
+      }
+    ],
+    "tags": {
+      "param": "compilerOptions\n \n- The compiler options to use.\ntsconfigPath\n \n- The path to the tsconfig file.\nonProgramCreatedOrUpdated\n \n- A callback function\nthat is called when the program is created or updated.",
+      "returns": ""
+    },
+    "type": {
+      "kind": "function",
+      "parameters": [
+        {
+          "kind": "parameter",
+          "name": "compilerOptions",
+          "type": {
+            "kind": "symbol",
+            "name": "ts.CompilerOptions",
+            "value": "CompilerOptions"
+          },
+          "required": true,
+          "rest": false,
+          "description": "- The compiler options to use.",
+          "declarations": [
+            {
+              "name": "compilerOptions",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts"
+            }
+          ],
+          "tags": {
+            "param": "compilerOptions\n \n- The compiler options to use."
+          }
+        },
+        {
+          "kind": "parameter",
+          "name": "tsconfigPath",
+          "type": {
+            "kind": "primitive",
+            "value": "string"
+          },
+          "required": true,
+          "rest": false,
+          "description": "- The path to the tsconfig file.",
+          "declarations": [
+            {
+              "name": "tsconfigPath",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts"
+            }
+          ],
+          "tags": {
+            "param": "tsconfigPath\n \n- The path to the tsconfig file."
+          }
+        },
+        {
+          "kind": "parameter",
+          "name": "onProgramCreatedOrUpdated",
+          "type": {
+            "kind": "function",
+            "parameters": [
+              {
+                "kind": "parameter",
+                "name": "program",
+                "type": {
+                  "kind": "symbol",
+                  "name": "ts.BuilderProgram",
+                  "value": "BuilderProgram"
+                },
+                "required": true,
+                "rest": false,
+                "description": "",
+                "declarations": [
+                  {
+                    "name": "program",
+                    "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts"
+                  }
+                ],
+                "tags": {}
+              }
+            ],
+            "members": [],
+            "returnType": {
+              "kind": "primitive",
+              "value": "void"
+            }
+          },
+          "required": true,
+          "rest": false,
+          "description": "- A callback function\nthat is called when the program is created or updated.",
+          "declarations": [
+            {
+              "name": "onProgramCreatedOrUpdated",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/createTypeScriptWatchProgram.ts"
+            }
+          ],
+          "tags": {
+            "param": "onProgramCreatedOrUpdated\n \n- A callback function\nthat is called when the program is created or updated."
+          }
+        }
+      ],
+      "members": [],
+      "returnType": {
+        "kind": "tuple",
+        "value": [
+          {
+            "kind": "symbol",
+            "name": "ts.BuilderProgram",
+            "value": "BuilderProgram"
+          },
+          {
+            "kind": "function",
+            "parameters": [],
+            "members": [],
+            "returnType": {
+              "kind": "primitive",
+              "value": "void"
+            }
+          }
+        ]
+      }
+    }
+  },
   {
     "name": "NestedStyleObject",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/styleTransform.ts",
@@ -411922,6 +412130,23 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             }
           ],
           "tags": {}
+        },
+        {
+          "kind": "property",
+          "name": "seed",
+          "required": true,
+          "type": {
+            "kind": "primitive",
+            "value": "string"
+          },
+          "description": "",
+          "declarations": [
+            {
+              "name": "seed",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/utils/types.ts"
+            }
+          ],
+          "tags": {}
         }
       ]
     }
@@ -411948,12 +412173,12 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
     }
   },
   {
-    "name": "default",
+    "name": "styleTransformer",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/styleTransform.ts",
     "description": "",
     "declarations": [
       {
-        "name": "default",
+        "name": "styleTransformer",
         "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/styleTransform.ts"
       }
     ],
@@ -412457,6 +412682,66 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
       }
     }
   },
+  {
+    "name": "getHash",
+    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/utils/createStyleObjectNode.ts",
+    "description": "Generate a deterministic hash that is unique to the seed +",
+    "declarations": [
+      {
+        "name": "getHash",
+        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/utils/createStyleObjectNode.ts"
+      }
+    ],
+    "tags": {},
+    "type": {
+      "kind": "function",
+      "parameters": [
+        {
+          "kind": "parameter",
+          "name": "node",
+          "type": {
+            "kind": "symbol",
+            "name": "ts.Node",
+            "value": "Node"
+          },
+          "required": true,
+          "rest": false,
+          "description": "",
+          "declarations": [
+            {
+              "name": "node",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/utils/createStyleObjectNode.ts"
+            }
+          ],
+          "tags": {}
+        },
+        {
+          "kind": "parameter",
+          "name": "context",
+          "type": {
+            "kind": "symbol",
+            "name": "TransformerContext",
+            "value": "TransformerContext"
+          },
+          "required": true,
+          "rest": false,
+          "description": "",
+          "declarations": [
+            {
+              "name": "context",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/utils/createStyleObjectNode.ts"
+            }
+          ],
+          "tags": {}
+        }
+      ],
+      "members": [],
+      "returnType": {
+        "kind": "primitive",
+        "value": "string"
+      }
+    }
+  },
   {
     "name": "getVariablesFromFiles",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/utils/getCssVariables.ts",
@@ -414172,6 +414457,23 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             }
           ],
           "tags": {}
+        },
+        {
+          "kind": "property",
+          "name": "seed",
+          "required": true,
+          "type": {
+            "kind": "primitive",
+            "value": "string"
+          },
+          "description": "",
+          "declarations": [
+            {
+              "name": "seed",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/utils/types.ts"
+            }
+          ],
+          "tags": {}
         }
       ]
     }
@@ -414538,6 +414840,23 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             }
           ],
           "tags": {}
+        },
+        {
+          "kind": "property",
+          "name": "seed",
+          "required": false,
+          "type": {
+            "kind": "primitive",
+            "value": "string"
+          },
+          "description": "Optional seed for the hash. This can be useful if you want each build to have a different hash.\nIf you provide the same seed, the same hash will be generated for every style.",
+          "declarations": [
+            {
+              "name": "seed",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/utils/types.ts"
+            }
+          ],
+          "tags": {}
         }
       ]
     }
@@ -414689,6 +415008,289 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
       }
     }
   },
+  {
+    "name": "default",
+    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpack-loader.ts",
+    "description": "",
+    "declarations": [
+      {
+        "name": "default",
+        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpack-loader.ts"
+      }
+    ],
+    "tags": {},
+    "type": {
+      "kind": "function",
+      "parameters": [
+        {
+          "kind": "parameter",
+          "name": "source",
+          "type": {
+            "kind": "primitive",
+            "value": "string"
+          },
+          "required": true,
+          "rest": false,
+          "description": "",
+          "declarations": [
+            {
+              "name": "source",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpack-loader.ts"
+            }
+          ],
+          "tags": {}
+        }
+      ],
+      "members": [],
+      "returnType": {
+        "kind": "primitive",
+        "value": "string"
+      }
+    }
+  },
+  {
+    "name": "StylingWebpackPlugin",
+    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts",
+    "description": "",
+    "declarations": [
+      {
+        "name": "StylingWebpackPlugin",
+        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+      }
+    ],
+    "tags": {},
+    "type": {
+      "kind": "object",
+      "properties": [
+        {
+          "kind": "property",
+          "name": "compilerOptions",
+          "type": {
+            "kind": "symbol",
+            "name": "CompilerOptions",
+            "value": "CompilerOptions"
+          },
+          "description": "",
+          "declarations": [
+            {
+              "name": "compilerOptions",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+            }
+          ],
+          "tags": {}
+        },
+        {
+          "kind": "property",
+          "name": "builderProgram",
+          "type": {
+            "kind": "symbol",
+            "name": "BuilderProgram",
+            "value": "BuilderProgram"
+          },
+          "description": "",
+          "declarations": [
+            {
+              "name": "builderProgram",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+            }
+          ],
+          "tags": {}
+        },
+        {
+          "kind": "property",
+          "name": "transformers",
+          "type": {
+            "kind": "array",
+            "value": {
+              "kind": "symbol",
+              "name": "TransformerFactory",
+              "typeParameters": [
+                {
+                  "kind": "symbol",
+                  "name": "SourceFile",
+                  "value": "any"
+                }
+              ],
+              "value": "any"
+            }
+          },
+          "description": "",
+          "declarations": [
+            {
+              "name": "transformers",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+            }
+          ],
+          "tags": {}
+        },
+        {
+          "kind": "property",
+          "name": "postTransform",
+          "type": {
+            "kind": "union",
+            "value": [
+              {
+                "kind": "parenthesis",
+                "value": {
+                  "kind": "function",
+                  "parameters": [
+                    {
+                      "kind": "parameter",
+                      "name": "code",
+                      "type": {
+                        "kind": "primitive",
+                        "value": "string"
+                      },
+                      "required": true,
+                      "rest": false,
+                      "description": "",
+                      "declarations": [
+                        {
+                          "name": "code",
+                          "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+                        }
+                      ],
+                      "tags": {}
+                    },
+                    {
+                      "kind": "parameter",
+                      "name": "id",
+                      "type": {
+                        "kind": "primitive",
+                        "value": "string"
+                      },
+                      "required": true,
+                      "rest": false,
+                      "description": "",
+                      "declarations": [
+                        {
+                          "name": "id",
+                          "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+                        }
+                      ],
+                      "tags": {}
+                    }
+                  ],
+                  "members": [],
+                  "returnType": {
+                    "kind": "union",
+                    "value": [
+                      {
+                        "kind": "primitive",
+                        "value": "string"
+                      },
+                      {
+                        "kind": "primitive",
+                        "value": "undefined"
+                      }
+                    ]
+                  }
+                }
+              },
+              {
+                "kind": "primitive",
+                "value": "undefined"
+              }
+            ]
+          },
+          "description": "",
+          "declarations": [
+            {
+              "name": "postTransform",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+            }
+          ],
+          "tags": {}
+        },
+        {
+          "kind": "property",
+          "name": "close",
+          "type": {
+            "kind": "function",
+            "parameters": [],
+            "members": [],
+            "returnType": {
+              "kind": "primitive",
+              "value": "void"
+            }
+          },
+          "description": "",
+          "declarations": [
+            {
+              "name": "close",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+            }
+          ],
+          "tags": {}
+        },
+        {
+          "kind": "property",
+          "name": "getLoaderOptions",
+          "type": {
+            "kind": "function",
+            "parameters": [],
+            "members": [],
+            "returnType": {
+              "kind": "unknown",
+              "value": "unknown",
+              "text": "SyntheticNode - ThisType"
+            }
+          },
+          "required": true,
+          "description": "",
+          "declarations": [
+            {
+              "name": "getLoaderOptions",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+            }
+          ],
+          "tags": {}
+        },
+        {
+          "kind": "property",
+          "name": "apply",
+          "type": {
+            "kind": "function",
+            "parameters": [
+              {
+                "kind": "parameter",
+                "name": "compiler",
+                "type": {
+                  "kind": "unknown",
+                  "value": "unknown",
+                  "text": "import('webpack').Compiler"
+                },
+                "required": true,
+                "rest": false,
+                "description": "",
+                "declarations": [
+                  {
+                    "name": "compiler",
+                    "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+                  }
+                ],
+                "tags": {}
+              }
+            ],
+            "members": [],
+            "returnType": {
+              "kind": "primitive",
+              "value": "void"
+            }
+          },
+          "required": true,
+          "description": "",
+          "declarations": [
+            {
+              "name": "apply",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/webpackPlugin.ts"
+            }
+          ],
+          "tags": {}
+        }
+      ]
+    }
+  },
   {
     "name": "calc",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/styling/lib/calc.ts",

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.2.1",
-    "@workday/canvas-kit-preview-react": "13.2.1",
-    "@workday/canvas-kit-react": "13.2.1",
-    "@workday/canvas-kit-react-fonts": "^13.2.1",
-    "@workday/canvas-kit-styling": "13.2.1",
+    "@workday/canvas-kit-labs-react": "13.2.2",
+    "@workday/canvas-kit-preview-react": "13.2.2",
+    "@workday/canvas-kit-react": "13.2.2",
+    "@workday/canvas-kit-react-fonts": "^13.2.2",
+    "@workday/canvas-kit-styling": "13.2.2",
     "@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.2.1",
-    "@workday/canvas-kit-preview-react": "13.2.1",
-    "@workday/canvas-kit-react": "13.2.1",
-    "@workday/canvas-kit-react-fonts": "^13.2.1",
-    "@workday/canvas-kit-styling": "13.2.1",
+    "@workday/canvas-kit-labs-react": "13.2.2",
+    "@workday/canvas-kit-preview-react": "13.2.2",
+    "@workday/canvas-kit-react": "13.2.2",
+    "@workday/canvas-kit-react-fonts": "^13.2.2",
+    "@workday/canvas-kit-styling": "13.2.2",
     "@workday/canvas-system-icons-web": "3.0.22",
     "@workday/canvas-tokens-web": "2.0.0"
   },

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

@@ -1,6 +1,6 @@
 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'
+import {system} from '@workday/canvas-tokens-web';
 
 
 # Canvas Kit Styling
@@ -27,7 +27,8 @@ 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.
+These packages work together to provide a CSS-in-JS experience during development while enabling
+optimized static CSS in production.
 
 ## Installation
 
@@ -55,74 +56,219 @@ const root = createRoot(domNode);
 root.render(<div className={myStyles}>Hello!</div>);
 ```
 
+## Style Merging
+
+The `@workday/canvas-kit-styling` package uses `@emotion/css` to inject styles during JavaScript
+evaluation time rather than `@emotion/react` or `@emotion/styled` injecting when a component is
+rendered. This means the Emotion cache needs to be known before any style is created. In order to
+properly merge styles with components using either dynamic styling package, the Emotion cache must
+be changed on any React application. Without this, styles will not be merged correctly when static
+and dynamic styles are used on the same element.
+
+If you're using Canvas Kit React, you should use the `<CanvasProvider>` which includes Emotion's
+`<CacheProvider>` with the proper cache already set. If you're not using Canvas Kit React, you
+should use the `<CacheProvider>`:
+
+```tsx
+// ONLY use if not using the <CanvasProvider>
+import {getCache} from '@workday/canvas-kit-styling';
+
+// in your application bootstrap
+const root = React.createRoot(document.getElementById('root'));
+
+root.render(
+  <CacheProvider value={getCache()}>
+    <App />
+  </CacheProvider>
+);
+```
+
+## Known issues
+
+### Hot Reloading
+
+Style merging works by using CSS specificity rather than JavaScript runtime. This can cause problems
+during hot reloading. If you specify all styles in the same file, hot reloading shouldn't result in
+any style merging problems. But if you use `extends` in `createStencil` that references another
+file, you may run into style merge issues.
+
+For example:
+
+```ts
+// base.tsx file
+export const baseStencil = createStencil({
+  base: {
+    color: 'red',
+  },
+});
+
+// extended.tsx file
+import {baseStencil} from './base';
+
+export const extendedStencil = createStencil({
+  extends: baseStencil,
+  base: {
+    color: 'blue',
+  },
+});
+```
+
+This will render correctly until you change `color` in `base.tsx` and get a hot reload:
+
+```tsx
+// base.tsx file
+export const baseStencil = createStencil({
+  base: {
+    color: 'purple',
+  },
+});
+```
+
+The hot reload will evaluate this update and inject a new style.
+
 ## 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.
+Canvas Kit Styling comes with a runtime that doesn't need anything special for development. The
+runtime uses `@emotion/css` to include your styles on the page. If you plan to use static
+compilation, we recommend enabling in production as well so you can fix static compilation errors as
+you develop rather than get errors only in production builds.
 
-## Production
+## Static compilation
 
-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:
+The `@workday/canvas-kit-styling-transform` package can to pre-build styles. This process takes
+style objects and turns them into CSS strings. This process moves serialization and hashing to build
+time rather than browser runtime when `@emotion/css` is processing styles. This will speed up
+production builds at runtime.
 
-```json
-{
-  "compilerOptions": {
-    // other options
-    "plugins": [
-      {
-        "transform": "@workday/canvas-kit-styling-transform",
-        "prefix": "css",
-        "fallbackFiles": [""]
-      }
-    ]
-  }
-}
+Static compilation has stricter requirements than when doing runtime styling. The static compiler
+uses the TypeScript type system to statically analyze style values and thus requires value types to
+be known by TypeScript. See [Restrictions](#restrictions).
+
+Static compilation may be required for server side rendering (SSR), especially when using React
+Server Components.
+
+### Hash generation
+
+Emotion generates hashes based on the serialized style object. This means a style should always give
+the same hash. Static styling hashes differently. Every `createStyles` or `createStencil` call will
+generate a unique hash even if the style object is the same. This is required for proper style
+merging because static styling doesn't give single class names, but rather merges styles using CSS
+specificity.
+
+For runtime development, the hash is always unique. For static compilation, the hash is based on the
+start and end character count in the source file of the style block. This is required for SSR so
+that the server and client agree on the same value during hydration. This means that while
+debugging, the hash depends on any code before it. If you add a `console.log` for example, the
+character index of a style block could shift which will generate a new hash.
+
+### Restrictions
+
+The static compiler uses the TypeScript type checker. The easiest way to think of these restrictions
+is if TypeScript knows the exact value, the static compiler will also know. A simple example:
+
+```ts
+// won't work - `value` is a type of `string` because `let` allows a value to be mutated
+let value = 'absolute'; // `string`
+
+const myStyles = createStyles({
+  position: value, // error - `string` isn't specific enough.
+});
+
+// will work - `value` is a type of `'absolute'` because `const` restricts to a string literal
+const value = 'absolute'; // `'absolute'`
+
+const myStyles = createStyles({
+  position: value, // works. If you mouse over `value` in your editor, you'll see the type is `'absolute'`
+});
 ```
 
-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.
+More complex examples may be objects:
 
-### Webpack
+```ts
+// won't work. TypeScript will not understand that the position will only be `'absolute'` and makes it a `string` instead
+const reusableStyles = {
+  position: 'absolute',
+}; // `{ position: string }`
 
-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.
+const myStyles = createStyles({
+  ...reusableStyles, // error - `position` is a `string` and not specific enough
+});
 
-In your webpack config, you add the following:
+// will work. Adding `as const` tells TypeScript the object is readonly and therefore no values can change
+const reusableStyles = {
+  position: 'absolute',
+} as const; // `{ readonly position: 'absolute' }`
+
+const myStyles = createStyles({
+  ...reusableStyles, // works. If you mouse over, the position is a string literal `'absolute'`
+});
+```
+
+Functions are a little more tricky and may require generics.
+
+```ts
+// generic makes the type be statically knowable
+function getPosition<V extends 'relative' | 'absolute'>(value: V): {position: V} {
+  return {position: value};
+}
+
+// mouse over `position` in your editor an the type will be `{ position: 'absolute' }`
+const position = getPosition('absolute'); // { position: 'absolute' }
+
+const myStyles = createStyles({
+  ...getPosition('absolute'), // works - `{ position: 'absolute' }`
+});
+```
+
+### Webpack
+
+The `@webpack/canvas-kit-styling-transform` package comes with a webpack loader that can be added to
+development and/or production.
 
 ```js
+// import the transform - CJS and ESM are supported
+import {StylingWebpackPlugin} from '@workday/canvas-kit-styling-transform';
+
+// somewhere only once. For static webpack config files, this can be near the top.
+// If inside Storybook, Gatsby, Next.js, etc configs, put inside the function that is called that
+// returns a webpack config
+const tsPlugin = const tsPlugin = new StylingWebpackPlugin({
+  tsconfigPath: path.resolve(__dirname, '../tsconfig.json'), // allows your TS config to be used
+  // A different tsconfig could be used if you want to use TS to transpile to something like ES2019 and
+  // also have Babel process the file.
+});
+
+// However you need to define rules.
+// This is different for using webpack directly or in Storybook/Gatsby/Next.js/etc
 {
   rules: [
     //...
     {
       test: /.\.tsx?$/,
-      loaders: [
-        // ts-loader
+      use: [
         {
-          loader: require.resolve('ts-loader'),
-          options: {
-            compiler: 'ts-patch/compiler',
-          },
-        },
-        // OR awesome-typescript-loader
-        {
-          loader: require.resolve('awesome-typescript-loader'),
+          loader: require.resolve('@workday/canvas-kit-styling-transform/webpack-loader'),
+          options: tsPlugin.getLoaderOptions(),
         },
       ],
+      enforce: 'pre'
     },
   ];
+  // We need to pass the plugin to Webpack's plugin list. Failure to do this will result in a
+  // production build hanging
+  plugins: [tsPlugin]
 }
 ```
 
 ## 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.
+Both approaches are intended to be used in tandem with the `cs` prop when applying styles to our
+components.
 
 ### `cs` Prop
 
@@ -132,7 +278,8 @@ everything together and applies `className` and `style` attributes to a React el
 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.
+> 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';
@@ -172,15 +319,15 @@ function MyComponent() {
 }
 ```
 
-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.
+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 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`
@@ -245,10 +392,10 @@ const ThemedCard = ({isDarkTheme, headerColor, elemProps}) => {
 };
 ```
 
-<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 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "14.0.0-alpha.1165-next.0",
+  "version": "14.0.0-alpha.1167-next.0",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -45,10 +45,10 @@
     "@emotion/styled": "^11.6.0",
     "@stackblitz/sdk": "^1.11.0",
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-labs-react": "^14.0.0-alpha.1165-next.0",
-    "@workday/canvas-kit-preview-react": "^14.0.0-alpha.1165-next.0",
-    "@workday/canvas-kit-react": "^14.0.0-alpha.1165-next.0",
-    "@workday/canvas-kit-styling": "^14.0.0-alpha.1165-next.0",
+    "@workday/canvas-kit-labs-react": "^14.0.0-alpha.1167-next.0",
+    "@workday/canvas-kit-preview-react": "^14.0.0-alpha.1167-next.0",
+    "@workday/canvas-kit-react": "^14.0.0-alpha.1167-next.0",
+    "@workday/canvas-kit-styling": "^14.0.0-alpha.1167-next.0",
     "@workday/canvas-system-icons-web": "^3.0.35",
     "@workday/canvas-tokens-web": "3.0.0-alpha.5",
     "markdown-to-jsx": "^7.2.0",
@@ -61,5 +61,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "24a44ff42a9e4424420a61c971515b923e470426"
+  "gitHead": "25670463a46bad451356d0550adac0de8b5209b0"
 }