@workday/canvas-kit-docs 16.0.0-alpha.0499-next.0 → 16.0.0

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": "15.1.4",
-    "@workday/canvas-kit-preview-react": "15.1.4",
-    "@workday/canvas-kit-react": "15.1.4",
-    "@workday/canvas-kit-react-fonts": "^15.1.4",
-    "@workday/canvas-kit-styling": "15.1.4",
+    "@workday/canvas-kit-labs-react": "16.0.0",
+    "@workday/canvas-kit-preview-react": "16.0.0",
+    "@workday/canvas-kit-react": "16.0.0",
+    "@workday/canvas-kit-react-fonts": "^16.0.0",
+    "@workday/canvas-kit-styling": "16.0.0",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

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

@@ -19,11 +19,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": "15.1.4",
-    "@workday/canvas-kit-preview-react": "15.1.4",
-    "@workday/canvas-kit-react": "15.1.4",
-    "@workday/canvas-kit-react-fonts": "^15.1.4",
-    "@workday/canvas-kit-styling": "15.1.4",
+    "@workday/canvas-kit-labs-react": "16.0.0",
+    "@workday/canvas-kit-preview-react": "16.0.0",
+    "@workday/canvas-kit-react": "16.0.0",
+    "@workday/canvas-kit-react-fonts": "^16.0.0",
+    "@workday/canvas-kit-styling": "16.0.0",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

package/dist/es6/utils/parseSpecFile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseSpecFile.d.ts","sourceRoot":"","sources":["../../../utils/parseSpecFile.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,aAAa,GAAG,OAAO,CAAC,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,aAAa,GAAG,OAAO,CAAC,EAAE,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA+E3E"}
+{"version":3,"file":"parseSpecFile.d.ts","sourceRoot":"","sources":["../../../utils/parseSpecFile.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,aAAa,GAAG,OAAO,CAAC,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,aAAa,GAAG,OAAO,CAAC,EAAE,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAsG3E"}

package/dist/es6/utils/parseSpecFile.js

@@ -15,14 +15,35 @@ export async function parseSpecFile(file) {
         const contents = await fs
             .readFile(file)
             .then(contents => contents.toString())
-            .then(contents => contents.replace(/import (.+) from .+/g, (substr, imports) => {
-            if (imports.includes('{')) {
-                return `const ${imports.replace(/[{}]/g, '')} = () => {}`;
+            .then(contents => 
+        // Strip imports before transpile. Use [\s\S] so multiline named imports are matched —
+        // otherwise typescript.transpile leaves `require(...)` calls that fail under eval.
+        contents.replace(/import\s+([\s\S]+?)\s+from\s+['"][^'"]+['"];?/g, (_substr, imports) => {
+            const trimmed = imports.trim();
+            if (trimmed.includes('{')) {
+                const names = trimmed
+                    .replace(/[{}]/g, '')
+                    .split(',')
+                    .map(part => {
+                    // support `Foo as Bar` and whitespace/newlines
+                    const pieces = part
+                        .trim()
+                        .split(/\s+as\s+|\s+/)
+                        .filter(Boolean);
+                    return pieces[pieces.length - 1];
+                })
+                    .filter(Boolean);
+                // Stub as both a component and a CSF story object (`Example.render`)
+                return names
+                    .map(name => `const ${name} = Object.assign(() => {}, {render: () => {}});`)
+                    .join('\n');
             }
-            if (/react/g.test(imports)) {
-                return `const React = {createElement: () => {}}`;
+            if (/react/i.test(trimmed)) {
+                return `const React = {createElement: () => {}};`;
             }
-            return '';
+            // default / namespace imports — stub the binding name
+            const name = trimmed.replace(/^\*\s+as\s+/, '').trim();
+            return name ? `const ${name} = () => {};` : '';
         })) // remove imports
             .then(contents => typescript.transpile(contents, { jsx: typescript.JsxEmit.React }))
             .then(contents => {

package/dist/mdx/16.0-UPGRADE-GUIDE.mdx

@@ -6,10 +6,157 @@ any questions.
 
 ## Why You Should Upgrade
 
-Soon to be...
+Canvas Kit v16 is a 1:1 component update that aligns every Canvas component to Sana's visual
+styling. Components ship that styling regardless of theme — you do not need to opt into the Sana
+Canvas theme for components to look correct.
+
+The Sana Canvas **theme** (CSS variables + `data-theme="sana-canvas"`) is a separate, opt-in step
+that updates brand colors, neutrals, surfaces, and shapes at the application level. See
+[Sana Canvas Theme](#sana-canvas-theme) below.
+
+
+## Sana Canvas Theme
+
+Your application is Sana-aligned out of the box when the Sana Canvas theme is applied. To opt in —
+brand neutrals, surfaces, and shapes — import the Sana CSS variables and set
+`data-theme="sana-canvas"` on `<html>`.
+
+> **Note:** All visual updates in this guide apply to both the Default Canvas theme and the Sana
+> Canvas theme unless specified otherwise.
+
+### Opting In
+
+Import the Sana variables **last** in your root CSS entry point. Sana's `[data-theme="sana-canvas"]`
+selector and `:root` have equal specificity — source order determines the winner.
+
+```css
+/* index.css — order matters */
+@import '@workday/canvas-tokens-web/css/base/_variables.css';
+@import '@workday/canvas-tokens-web/css/brand/_variables.css';
+@import '@workday/canvas-tokens-web/css/component/_variables.css';
+@import '@workday/canvas-tokens-web/css/system/_variables.css';
+/* Sana last: [data-theme="sana-canvas"] and :root have equal specificity (0,1,0),
+   so when both match <html> the cascade falls back to source order. */
+@import '@workday/canvas-tokens-web/css/sana/_variables.css';
+```
+
+Set `data-theme="sana-canvas"` on `<html>` when you control the document root (preferred). Nested
+elements are not enough for portaled popups (including all Canvas Kit popups such as menus,
+selects, modals, and toasts) — those render under `document.body` via React portals, outside the
+parent component's DOM hierarchy, and only inherit theme from `<html>`, or from
+`sanaCanvasProviderTheme` on `CanvasProvider` when `<html>` is unavailable.
+
+```html
+<html lang="en" data-theme="sana-canvas"></html>
+```
+
+> **Gotcha:** There is no `[data-theme="canvas"]` rule. The sana file only defines
+> `[data-theme="sana-canvas"]` overrides, so removing the attribute is how you get classic Canvas —
+> there's nothing to undo it with.
+
+### What Changes When You Opt In
+
+Things that change are primary brand consumers and Sana's neutral color scale
+(`--cnvs-brand-neutral-*`, which replaces classic slate neutrals). Verified against
+`@workday/canvas-tokens-web/css/sana/_variables.css`:
+
+- **Brand primary consumers flip.** `--cnvs-sys-color-brand-accent-primary` and `-accent-action`
+  re-point from blue to `--cnvs-brand-neutral-975`, and `-brand-fg-primary-default/-strong` to
+  `--cnvs-brand-neutral-a900/-a950`. `PrimaryButton`, brand links, and selected states are what
+  visibly change.
+- **Focus does not.** `--cnvs-sys-color-brand-focus-primary` and `-border-primary` stay `blue-500`.
+- **`--cnvs-brand-primary-600` is intentionally _not_ redefined** — it stays the consumer's brand
+  hook.
+- **The full neutral color scale is replaced** (`--cnvs-brand-neutral-*`, all steps plus alphas),
+  plus selected `critical`, `caution`, `positive`, shapes (`sm`, `xs`, `xxl`, `xxxl`),
+  surfaces/overlays, and chart ramps.
+
+### Scoped Theming
+
+The `CanvasProvider` theming updates in
+[#4060](https://github.com/Workday/canvas-kit/pull/4060) are for **scoped** use cases — embedding
+Canvas in another brand, multi-tenant sections, and popup parity when you cannot set
+`data-theme="sana-canvas"` on `<html>`. Application teams that control `<html>` and import the
+Sana variables globally do not need a `theme` prop for app-wide Sana.
+
+For the scoped theming API, see our
+[Theming documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs).
+
+#### Default Scope Change for Legacy Themes
+
+**Important:** If you previously used `canvas.palette.<color>.main` only (without other palette properties)
+to scope-theme your application, the default behavior has changed. In v16:
+
+- **Before v16:** Setting only `palette.primary.main` would automatically generate a full color ramp
+  (lightest, lighter, light, dark, darkest, contrast) and apply broad `system.color.brand.*` forwarding.
+- **In v16:** Setting only `palette.primary.main` defaults to `'brand'` scope, which applies a narrower
+  set of variables (PrimaryButton and selected states only).
+
+To restore the previous behavior, explicitly set `themeScope: 'full'`:
+
+```jsx
+// v15 behavior (implicit full scope)
+<CanvasProvider theme={{canvas: {palette: {primary: {main: '#FF00FF'}}}}} />
+
+// v16 - to get the same behavior as v15
+<CanvasProvider
+  theme={{canvas: {palette: {primary: {main: '#FF00FF'}}}}}
+  themeScope="full"
+/>
+```
+
+This change provides more control over theming scope and prevents unintended overrides, but teams
+relying on the auto-generated color ramp need to explicitly opt into `'full'` scope.
+
+### Simplified Sana Canvas Setup
+
+If you can set `data-theme="sana-canvas"` on `<html>`, you no longer need to pass
+`sanaCanvasProviderTheme` to CanvasProvider. Popups are called out specifically because Canvas Kit
+renders them through React portals under `document.body` — outside the parent component's DOM
+hierarchy — so they inherit CSS variables from `<html>`, not from a nested wrapper.
+
+**Before:**
+```tsx
+import {CanvasProvider, sanaCanvasProviderTheme} from '@workday/canvas-kit-react/common';
+
+<CanvasProvider theme={sanaCanvasProviderTheme}>
+  <App />
+</CanvasProvider>
+```
+
+**After (when you control `<html>`):**
+```tsx
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+
+// <html data-theme="sana-canvas">
+<CanvasProvider>
+  <App />
+</CanvasProvider>
+```
+
+**Still required — cannot set `data-theme` on `<html>`:** embedded apps, microfrontends, and
+third-party shells often cannot set attributes on the document root. Nested `data-theme` does not
+reach portaled popups (including all Canvas Kit popups such as menus, selects, modals, and toasts).
+Pass both `data-theme="sana-canvas"` (in-tree UI) and `sanaCanvasProviderTheme` (popup forwarding):
+
+```tsx
+import {CanvasProvider, sanaCanvasProviderTheme} from '@workday/canvas-kit-react/common';
+
+<CanvasProvider theme={sanaCanvasProviderTheme} data-theme="sana-canvas">
+  <App />
+</CanvasProvider>
+```
+
+If you control `<html>` and see a console warning about unnecessary theme usage, you can safely
+remove the theme prop.
 
 ## Table of Contents
 
+- [Sana Canvas Theme](#sana-canvas-theme)
+  - [Opting In](#opting-in)
+  - [What Changes When You Opt In](#what-changes-when-you-opt-in)
+  - [Scoped Theming](#scoped-theming)
+  - [Simplified Sana Canvas Setup](#simplified-sana-canvas-setup)
 - [Codemod](#codemod)
   - [Instructions](#instructions)
   - [Codemod Transformations for Icons](#codemod-transformations-for-icons)
@@ -643,8 +790,6 @@ If you customize `brand.success.base` in your theme, please verify the following
 - Prefer a `brand.success.base` value that is dark enough to pair with a light foreground. If your
   brand requires a light success color, you may need to override the component styles so the
   foreground uses a darker, paired contrast color instead of white.
-  > **Note:** All visual updates apply to both the Default Canvas theme and new Sana Canvas theme
-  > unless specified otherwise.
 
 #### Checkbox