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

package/dist/es6/lib/docs.js

@@ -392762,7 +392762,11 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
           },
           {
             "kind": "string",
-            "value": "alternate"
+            "value": "alternative"
+          },
+          {
+            "kind": "string",
+            "value": "overlay"
           }
         ]
       }
@@ -393578,7 +393582,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             "name": "SidePanelVariant",
             "value": "SidePanelVariant"
           },
-          "description": "The style variant of the side panel. 'standard' uses a lighter gray background (`system.color.bg.alt.softer`), no depth. 'alternate' uses a white background with depth (`system.color.bg.default` and level 3 depth).",
+          "description": "The style variant of the side panel.\n- `'standard'`: navigation surface background (`system.legacy.color.surface.navigation`), no depth.\n- `'alternative'`: raised surface background (`system.legacy.color.surface.raised`), no depth.\n- `'overlay'`: default surface background (`system.legacy.color.surface.default`) with level 6 depth, for panels that need to look lifted off the page. This is a visual treatment only — it adds no dialog semantics, focus trapping, or backdrop.",
           "declarations": [
             {
               "name": "variant",
@@ -393732,7 +393736,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
         {
           "name": "ToggleButton",
           "symbol": "SidePanelToggleButton",
-          "description": "`SidePanel.ToggleButton` is a control that toggles between expanded and collapsed states.\nIt must be used within the `SidePanel` component as a child. For accessibility purposes,\nit should be the first focusable element in the panel.\n\nThe button automatically receives `aria-controls`, `aria-expanded`, and `aria-labelledby`\nattributes from the model.",
+          "description": "`SidePanel.ToggleButton` is a control that toggles between expanded and collapsed states.\nIt must be used within the `SidePanel` component as a child. For accessibility purposes,\nit should be the first focusable element in the panel.\n\nThe button automatically receives `aria-controls` (the panel's `id`), `aria-pressed` (`true`\nwhen the panel is collapsed), and `aria-describedby` (the heading's `id`) from the model.\nProvide a static `aria-label` for the button's accessible name — `aria-pressed` already\nconveys the state, so the label should not change between states.",
           "declarations": [
             {
               "name": "ToggleButton",
@@ -395515,7 +395519,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
   {
     "name": "useSidePanelToggleButton",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/react/side-panel/lib/SidePanelToggleButton.tsx",
-    "description": "",
+    "description": "Adds the necessary ARIA attributes to the SidePanel's toggle button.\nThis includes `aria-controls` pointing at the panel, `aria-pressed` to convey the collapsed\nstate, and `aria-describedby` pointing at the panel's heading.",
     "declarations": [
       {
         "name": "useSidePanelToggleButton",
@@ -395829,7 +395833,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             "value": "string"
           },
           "required": false,
-          "description": "The unique ID for the panel's label element. If not provided, a unique ID will be generated.\nThis ID is used for the `aria-labelledby` attribute on both the panel and toggle button.",
+          "description": "The unique ID for the panel's label element. If not provided, a unique ID will be generated.\nThis ID is used for the `aria-labelledby` attribute on the panel and the `aria-describedby`\nattribute on the toggle button.",
           "declarations": [
             {
               "name": "labelId",
@@ -395925,7 +395929,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             "kind": "primitive",
             "value": "string"
           },
-          "description": "The unique ID for the panel's label element. Used for `aria-labelledby` on the panel\nand toggle button to provide an accessible name.",
+          "description": "The unique ID for the panel's label element. Used for `aria-labelledby` on the panel to\nprovide its accessible name, and for `aria-describedby` on the toggle button.",
           "declarations": [
             {
               "name": "labelId",
@@ -396270,7 +396274,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             "value": "string"
           },
           "required": false,
-          "description": "The unique ID for the panel's label element. If not provided, a unique ID will be generated.\nThis ID is used for the `aria-labelledby` attribute on both the panel and toggle button.",
+          "description": "The unique ID for the panel's label element. If not provided, a unique ID will be generated.\nThis ID is used for the `aria-labelledby` attribute on the panel and the `aria-describedby`\nattribute on the toggle button.",
           "declarations": [
             {
               "name": "labelId",
@@ -396701,7 +396705,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             "kind": "primitive",
             "value": "string"
           },
-          "description": "The unique ID for the panel's label element. Used for `aria-labelledby` on the panel\nand toggle button to provide an accessible name.",
+          "description": "The unique ID for the panel's label element. Used for `aria-labelledby` on the panel to\nprovide its accessible name, and for `aria-describedby` on the toggle button.",
           "declarations": [
             {
               "name": "labelId",

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

@@ -20,8 +20,8 @@ Soon to be...
   - [Avatar](#avatar)
   - [Buttons](#buttons)
     - [Delete Button Outline Variant](#delete-button-outline-variant)
-	- [Container Components](#container-components)
-	  - [Card](#card)
+  - [Container Components](#container-components)
+    - [Card](#card)
     - [Expandable](#expandable)
   - [Indicators](#indicators)
     - [Banner](#banner)
@@ -50,6 +50,7 @@ Soon to be...
     - [Pagination](#pagination)
   - [Popup](#popup)
   - [Segmented Control](#segmented-control)
+  - [Side Panel](#side-panel)
   - [Table](#table)
   - [Toast](#toast)
   - [Tooltip](#tooltip)
@@ -261,7 +262,8 @@ import {DeleteButton} from '@workday/canvas-kit-react/button';
 
 #### Alt Variant Support
 
-Several container components now support an `alt` variant that provides an elevated surface appearance:
+Several container components now support an `alt` variant that provides an elevated surface
+appearance:
 
 - `Menu.Card` - Can use `variant="alt"` for elevated menu styling
 - `Dialog.Card` - Can use `variant="alt"` for elevated dialog styling
@@ -269,7 +271,8 @@ Several container components now support an `alt` variant that provides an eleva
 - `Toast` - Can use `variant="alt"` for elevated toast styling
 - `Tooltip` - Can use `variant="alt"` for elevated tooltip styling
 
-The `alt` variant uses `system.sana.color.surface.elevated` background with inverse borders, providing visual hierarchy and depth to these components when placed on an alt background.
+The `alt` variant uses `system.sana.color.surface.elevated` background with inverse borders,
+providing visual hierarchy and depth to these components when placed on an alt background.
 
 ```tsx
 // Examples of using the alt variant
@@ -291,17 +294,20 @@ The `alt` variant uses `system.sana.color.surface.elevated` background with inve
 
 #### Card
 
-**PR:** [#4014](https://github.com/Workday/canvas-kit/pull/4014), [#4088](https://github.com/Workday/canvas-kit/pull/4088)
+**PR:** [#4014](https://github.com/Workday/canvas-kit/pull/4014),
+[#4088](https://github.com/Workday/canvas-kit/pull/4088)
 
 ##### Variant Changes
 
 The `Card` component's variants have been updated:
+
 - **Removed:** The `borderless` variant has been removed and replaced with `alt`
 - **New:** The `alt` variant provides an elevated surface with inverse borders
 - **Updated:** The default variant now has a visible border
 - The `tonal` variant now uses a `system.legacy.color.surface.alt.strong` background.
 
-**Note:** If you were previously using `variant="borderless"`, you should use `variant="alt"` instead. While the styles are different, both where intended to be used on an `alt` background.
+**Note:** If you were previously using `variant="borderless"`, you should use `variant="alt"`
+instead. While the styles are different, both where intended to be used on an `alt` background.
 
 🤖 The codemod will automatically update `variant="borderless"` to `variant="alt"`.
 
@@ -326,7 +332,8 @@ The `Card` component's variants have been updated:
 - Card's border radius is now managed via the new `cornerShapeStencil` (see
   [New Utilities](#new-utilities)).
 - The default variant now includes a visible border (`system.color.border.default`).
-- The `alt` variant uses an elevated surface color (`system.sana.color.surface.elevated`) with inverse borders.
+- The `alt` variant uses an elevated surface color (`system.sana.color.surface.elevated`) with
+  inverse borders.
 
 #### Expandable
 
@@ -815,6 +822,62 @@ Run the Canvas Kit v16 codemod (`updateHyperlinkProps`) to migrate automatically
 - Container padding changed to `padding.md` (16px) including for mobile devices.
 - On mobile devices, the container padding remains `padding.md` (16px).
 
+### Side Panel
+
+**PR:** [#4107](https://github.com/Workday/canvas-kit/pull/4107)
+
+#### Breaking Changes
+
+The `variant` prop on `SidePanel` no longer accepts `alternate`. It has been renamed to `overlay` to
+describe what the variant is for — a panel that floats above page content — because a second
+non-overlay variant now occupies the "alternative surface" role.
+
+```tsx
+import {SidePanel} from '@workday/canvas-kit-react/side-panel';
+
+// Before
+<SidePanel variant="alternate">{/* ... */}</SidePanel>
+
+// After
+<SidePanel variant="overlay">{/* ... */}</SidePanel>
+```
+
+> 🤖 The `v16` codemod will rename `variant="alternate"` to `variant="overlay"` as shown above. It
+> only transforms `SidePanel` imported from `@workday/canvas-kit-react`; the deprecated `SidePanel`
+> in `@workday/canvas-kit-preview-react` is left alone.
+
+If you were using `alternate` for a panel that sits inline with page content rather than over it,
+switch to the new `alternative` variant instead of `overlay` to avoid picking up the elevation
+shadow.
+
+#### New API
+
+- `variant="alternative"` — uses a raised surface (`system.legacy.color.surface.raised`) with no
+  depth. Use it for panels that need to stand out from the page background while remaining part of
+  the page layout.
+
+The full set of variants is now:
+
+| Variant       | Surface                                  | Depth |
+| ------------- | ---------------------------------------- | ----- |
+| `standard`    | `system.legacy.color.surface.navigation` | None  |
+| `alternative` | `system.legacy.color.surface.raised`     | None  |
+| `overlay`     | `system.legacy.color.surface.default`    | 6     |
+
+#### Visual Updates
+
+- The `overlay` variant's box-shadow updated from `system.depth[3]` to `system.depth[6]`.
+- `SidePanel.ToggleButton`'s default icon changed from `extendIcon` to `sidebarLeftIcon`. The icon
+  no longer rotates as the panel expands and collapses: it keeps a single orientation in LTR and is
+  mirrored horizontally in RTL.
+- `SidePanel.ToggleButton`'s width changed from `gap.lg` (24px) to `size.md` (40px), and its top
+  offset changed from `gap.lg` (24px) to `12px`.
+- `SidePanel.Heading` padding changed from a symmetric `padding.xs` (8px) to `padding.sm` (12px)
+  with a `paddingInlineStart` of `padding.md` (16px), and it now has a `minHeight` of `size.xxl`
+  (64px) so the heading lines up with the toggle button and the collapsed panel width.
+- `SidePanel.Heading` now lays out its children with flexbox and centers them vertically, so an icon
+  passed alongside the heading text aligns without extra styling.
+
 ### Table
 
 #### Visual Updates

package/dist/mdx/react/side-panel/SidePanel.mdx

@@ -1,15 +1,17 @@
 import {
   ExampleCodeBlock,
-  SymbolDoc,
   Specifications,
+  StorybookStatusIndicator,
+  SymbolDoc,
 } from '@workday/canvas-kit-docs';
+
+import AlwaysOpen from './examples/AlwaysOpen';
 import Basic from './examples/Basic';
-import Heading from './examples/Heading';
-import AlternatePanel from './examples/Variant';
 import ExternalControl from './examples/ExternalControl';
-import RightOrigin from './examples/RightOrigin';
-import AlwaysOpen from './examples/AlwaysOpen';
+import Heading from './examples/Heading';
 import OnStateTransition from './examples/OnStateTransition';
+import RightOrigin from './examples/RightOrigin';
+import {AlternativePanel, OverlayPanel} from './examples/Variant';
 
 
 # Canvas Kit Side Panel
@@ -54,15 +56,16 @@ import {SidePanel, useSidePanelModel} from '@workday/canvas-kit-react/side-panel
 
 ### Component API Changes
 
-| Preview                                        | Main                                              |
-| ---------------------------------------------- | ------------------------------------------------- |
-| `<SidePanel {...panelProps}>`                  | `<SidePanel model={model}>` or just `<SidePanel>` |
-| `<SidePanel.ToggleButton {...controlProps} />` | `<SidePanel.ToggleButton />`                      |
-| `<Heading {...labelProps}>`                    | `<SidePanel.Heading>Panel Title</SidePanel.Heading>`              |
-| `expanded` prop on SidePanel                   | Managed by model's `transitionState`              |
-| `touched` prop on SidePanel                    | Managed internally                                |
-| `onExpandedChange` callback                    | Use `onStateTransition` and derive expanded state |
-| `onStateTransition` on component               | `onStateTransition` on model config               |
+| Preview                                        | Main                                                 |
+| ---------------------------------------------- | ---------------------------------------------------- |
+| `<SidePanel {...panelProps}>`                  | `<SidePanel model={model}>` or just `<SidePanel>`    |
+| `<SidePanel.ToggleButton {...controlProps} />` | `<SidePanel.ToggleButton />`                         |
+| `<Heading {...labelProps}>`                    | `<SidePanel.Heading>Panel Title</SidePanel.Heading>` |
+| `expanded` prop on SidePanel                   | Managed by model's `transitionState`                 |
+| `touched` prop on SidePanel                    | Managed internally                                   |
+| `onExpandedChange` callback                    | Use `onStateTransition` and derive expanded state    |
+| `onStateTransition` on component               | `onStateTransition` on model config                  |
+| `variant="alternate"`                          | `variant="overlay"` (rename only, same styling)      |
 
 ### Code Migration Example
 
@@ -140,13 +143,74 @@ heading while keeping it accessible to screen readers.
 
 <ExampleCodeBlock code={Heading} />
 
-### Alternate Variant
+### Variants
+
+`SidePanel` supports three variants, which you supply as a top-level `variant` prop. They differ
+only in surface color and depth — the layout, animation, and accessibility behavior is identical.
+
+| Variant       | Surface                                  | Depth | Use for                                                                       |
+| ------------- | ---------------------------------------- | ----- | ----------------------------------------------------------------------------- |
+| `standard`    | `system.legacy.color.surface.navigation` | None  | The default. Panels that are part of the page layout, such as navigation.     |
+| `alternative` | `system.legacy.color.surface.raised`     | None  | Panels that need to stand out from the page background while staying in-flow. |
+| `overlay`     | `system.legacy.color.surface.default`    | 6     | Panels that need to look lifted off the page. Styling only — see below.       |
+
+#### Alternative
+
+The `alternative` variant uses a raised surface color with no depth. Because it doesn't cast a
+shadow, it remains part of the page layout and is a good fit when the panel sits next to content on
+a tinted or gray background.
+
+<ExampleCodeBlock code={AlternativePanel} />
+
+#### Overlay
+
+The `overlay` variant is a **visual treatment only**. It gives the panel the default surface color
+and depth 6 so it reads as floating above the page, which is the same elevation `Modal.Card` uses.
+The name describes how the panel looks; it does not turn `SidePanel` into a dialog. This variant is
+the `alternate` variant from `@workday/canvas-kit-preview-react`, renamed — it has never carried any
+behavior beyond the surface and shadow.
+
+Reach for it when a panel needs to look lifted off the page — for example an overlay menu or a
+filter panel you position over content with your own CSS. `SidePanel` still renders a `<section>`
+that participates in the page and the tab order exactly like `standard` and `alternative` do.
+
+Setting `variant="overlay"` does **not** add any of the following, and `SidePanel` has no props to
+opt into them:
+
+- `role="dialog"` or `aria-modal` — the element stays a plain `<section>` named by its heading
+- A focus trap, initial focus, or return focus
+- A backdrop / overlay element
+- Close on **Escape** or close on outside click
+- `aria-hidden` on sibling content, or body scroll locking
+- Positioning — the panel is in normal flow until you position it yourself
+
+> **Accessibility Note**: If you need a panel that genuinely blocks the rest of the page, use
+> [`Modal`](https://workday.github.io/canvas-kit/?path=/docs/components-popups-modal--docs) instead
+> of assembling that behavior around `SidePanel`. `Modal` composes `useInitialFocus`,
+> `useReturnFocus`, `useFocusTrap`, `useCloseOnEscape`, `useCloseOnOverlayClick`,
+> `useAssistiveHideSiblings`, and `useDisableBodyScroll` and is tested as a unit. Those hooks are
+> built on `usePopupModel` and cannot be added to `useSidePanelModel`, so a hand-rolled version on
+> top of `SidePanel` will not get you the same guarantees.
+
+**Keyboard and focus behavior:** because the variant adds no dialog semantics, keyboard behavior is
+identical to the other two variants and no focus management is expected of you:
+
+- **Tab** / **Shift + Tab** move through the panel's focusable elements in DOM order and then
+  continue into the rest of the page. Focus is **not** trapped.
+- Focus does not move when the panel expands or collapses. It stays on `SidePanel.ToggleButton`,
+  which reports the new state through `aria-pressed`.
+- **Escape** does nothing. Collapsing happens only through the toggle button or
+  `model.events.collapse()`.
+- Collapsing hides the panel's content visually but does not remove it from the DOM. Keep the toggle
+  button as the first focusable element in the panel — see [Accessibility](#accessibility) — so
+  keyboard users reach the control before the content it hides.
 
-`SidePanel` has one variant, `alternate`, which you can supply as a top-level prop. Default depth of
-`alternate` variant is 5, if `alternate` SidePanel has an overlay behavior the depth 6 should be
-used (this case is covered in the Examples section).
+If you do position this variant over other content, treat it as a non-modal region: the content
+behind it stays reachable by keyboard and by screen reader, and users can tab out of the panel while
+it visually covers the page. That mismatch between what the panel looks like and how it behaves is
+the reason to prefer `Modal` for anything the user must dismiss before continuing.
 
-<ExampleCodeBlock code={AlternatePanel} />
+<ExampleCodeBlock code={OverlayPanel} />
 
 ### External Control
 
@@ -276,8 +340,8 @@ element, including `id`, `aria-labelledby`, and `onTransitionEnd`.
 
 ### useSidePanelToggleButton
 
-The `useSidePanelToggleButton` elemProps hook provides ARIA attributes for the toggle
-button, including `aria-controls`, `aria-pressed`, and `aria-describedby`.
+The `useSidePanelToggleButton` elemProps hook provides ARIA attributes for the toggle button,
+including `aria-controls`, `aria-pressed`, and `aria-describedby`.
 
 <SymbolDoc name="useSidePanelToggleButton" fileName="/react/" />
 

package/dist/mdx/react/side-panel/examples/Basic.tsx

@@ -18,9 +18,9 @@ export default () => {
   return (
     <Flex cs={viewPortStyles}>
       <SidePanel>
-        <SidePanel.Heading size="small">
+        <SidePanel.Heading>
           <Flex cs={flexHeadingStyles}>
-            <ExpressiveIcon icon={rocketIcon} />
+            <ExpressiveIcon icon={rocketIcon} size="xs" />
             Tasks Panel
           </Flex>
         </SidePanel.Heading>

package/dist/mdx/react/side-panel/examples/RightOrigin.tsx

@@ -4,7 +4,6 @@ import {Flex} from '@workday/canvas-kit-react/layout';
 import {SidePanel, useSidePanelModel} from '@workday/canvas-kit-react/side-panel';
 import {Text} from '@workday/canvas-kit-react/text';
 import {createStyles, px2rem} from '@workday/canvas-kit-styling';
-import {system} from '@workday/canvas-tokens-web';
 
 // local helper hook for setting content direction;
 import {useDirection} from './useDirection';
@@ -19,7 +18,6 @@ const stylesOverride = {
   panel: createStyles({
     alignItems: 'center',
     justifyContent: 'flex-end',
-    padding: system.padding.md,
   }),
   main: createStyles({
     alignItems: 'center',

package/dist/mdx/react/side-panel/examples/Variant.tsx

@@ -33,9 +33,9 @@ export default () => {
   return (
     <CanvasProvider dir={direction}>
       <Flex cs={stylesOverride.viewport}>
-        <SidePanel variant="alternate">
+        <SidePanel variant="overlay">
           <SidePanel.ToggleButton aria-label="Collapse View" />
-          <SidePanel.Heading size="small">Alternate Panel</SidePanel.Heading>
+          <SidePanel.Heading size="small">Overlay Panel</SidePanel.Heading>
         </SidePanel>
         <Flex as="main" cs={stylesOverride.main}>
           <Text as="p" typeLevel="body.large">
@@ -49,3 +49,18 @@ export default () => {
     </CanvasProvider>
   );
 };
+
+const viewportStyles = createStyles({
+  height: px2rem(320),
+});
+
+export default () => {
+  return (
+    <Flex cs={viewportStyles}>
+      <SidePanel variant="alternative">
+        <SidePanel.ToggleButton aria-label="Collapse View" />
+        <SidePanel.Heading size="small">Alternative Panel</SidePanel.Heading>
+      </SidePanel>
+    </Flex>
+  );
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "16.0.0-alpha.0492-next.0",
+  "version": "16.0.0-alpha.0494-next.0",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -47,10 +47,10 @@
     "@stackblitz/sdk": "^1.11.0",
     "@storybook/csf": "0.0.1",
     "@workday/canvas-expressive-icons-web": "1.0.2",
-    "@workday/canvas-kit-labs-react": "^16.0.0-alpha.0492-next.0",
-    "@workday/canvas-kit-preview-react": "^16.0.0-alpha.0492-next.0",
-    "@workday/canvas-kit-react": "^16.0.0-alpha.0492-next.0",
-    "@workday/canvas-kit-styling": "^16.0.0-alpha.0492-next.0",
+    "@workday/canvas-kit-labs-react": "^16.0.0-alpha.0494-next.0",
+    "@workday/canvas-kit-preview-react": "^16.0.0-alpha.0494-next.0",
+    "@workday/canvas-kit-react": "^16.0.0-alpha.0494-next.0",
+    "@workday/canvas-kit-styling": "^16.0.0-alpha.0494-next.0",
     "@workday/canvas-system-icons-web": "5.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.13",
     "markdown-to-jsx": "^7.2.0",
@@ -63,5 +63,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "27691d763b93d270f78808ca298848d405c888e1"
+  "gitHead": "7bde57a5a6d4e41fd4a2e08f9f035c609ff4a8f0"
 }