@kaizen/components 0.0.0-canary-test-cherry-picked-updates-20250702235156 → 0.0.0-canary-ssr-generic-modal-1-20250709023540

package/src/__next__/Icon/_docs/Icon--migration-guide.mdx

@@ -1,12 +1,20 @@
-import { Canvas, Meta, Controls, Story } from '@storybook/blocks'
-import { ResourceLinks, KAIOInstallation, LinkTo } from '~storybook/components'
+import { Meta, Story } from '@storybook/blocks'
+import { LinkTo } from '~storybook/components'
 import * as IconStories from './Icon.docs.stories'
 
 <Meta title="Components/Icon/Migration guide" />
 
 # Icon migration guide
 
-This is a short guide to assist in migration from the old to new Icon component.
+## Audience
+
+This guide is relevant for Kaizen All-In-One (KAIO) v1 consumers.
+
+## Purpose
+
+This guide provides instructions for migrating icon usage from the `deprecated` (`@kaizen/components`) `*Icon` components to the `next` (`@kaizen/components/next`) `Icon` component.
+
+This migration is a prerequisite for [migrating to KAIO v2](/docs/releases-upcoming-major-releases--docs).
 
 ## Codemod
 

package/src/__next__/Icon/_docs/Icon.docs.module.css

@@ -1,15 +1,17 @@
-.interactiveIcon {
-  position: relative;
-  background: none;
-  padding: 0;
-  color: var(--color-blue-500);
+@layer kz-components {
+  .interactiveIcon {
+    position: relative;
+    background: none;
+    padding: 0;
+    color: var(--color-blue-500);
 
-  &:hover {
-    color: var(--color-blue-400);
+    &:hover {
+      color: var(--color-blue-400);
+    }
   }
-}
 
-.interactiveIcon:focus {
-  outline: var(--border-focus-ring-border-width) var(--border-focus-ring-border-style)
-    var(--color-blue-500);
+  .interactiveIcon:focus {
+    outline: var(--border-focus-ring-border-width) var(--border-focus-ring-border-style)
+      var(--color-blue-500);
+  }
 }

package/src/__next__/Menu/Menu.module.css

@@ -1,32 +1,34 @@
-.menu {
-  background-color: var(--color-white);
-  color: var(--color-purple-800);
-  width: 248px;
-  max-height: 22rem;
-  overflow: auto;
-  padding-block: var(--spacing-6);
-  outline: none;
-  border-radius: var(--border-solid-border-radius);
-  box-shadow: var(--shadow-large-box-shadow);
-}
+@layer kz-components {
+  .menu {
+    background-color: var(--color-white);
+    color: var(--color-purple-800);
+    width: 248px;
+    max-height: 22rem;
+    overflow: auto;
+    padding-block: var(--spacing-6);
+    outline: none;
+    border-radius: var(--border-solid-border-radius);
+    box-shadow: var(--shadow-large-box-shadow);
+  }
 
-.menu :global(.react-aria-Header) {
-  font-family: var(--typography-heading-6-font-family);
-  font-size: var(--typography-heading-6-font-size);
-  letter-spacing: var(--typography-heading-6-letter-spacing);
-  font-weight: var(--typography-heading-6-font-weight);
-  line-height: var(--typography-heading-6-line-height);
-  padding: var(--spacing-6) 10px;
-  margin-inline: var(--spacing-6);
-}
+  .menu :global(.react-aria-Header) {
+    font-family: var(--typography-heading-6-font-family);
+    font-size: var(--typography-heading-6-font-size);
+    letter-spacing: var(--typography-heading-6-letter-spacing);
+    font-weight: var(--typography-heading-6-font-weight);
+    line-height: var(--typography-heading-6-line-height);
+    padding: var(--spacing-6) 10px;
+    margin-inline: var(--spacing-6);
+  }
 
-.menu section:not(:last-of-type) {
-  &::after {
-    width: 100%;
-    height: 1px;
-    background-color: var(--border-solid-border-color);
-    content: '';
-    display: block;
-    margin-block: var(--spacing-6);
+  .menu section:not(:last-of-type) {
+    &::after {
+      width: 100%;
+      height: 1px;
+      background-color: var(--border-solid-border-color);
+      content: '';
+      display: block;
+      margin-block: var(--spacing-6);
+    }
   }
 }

package/src/__next__/Menu/MenuItem.module.css

@@ -1,46 +1,48 @@
-.item {
-  display: block;
-  font-family: var(--typography-paragraph-body-font-family);
-  font-size: var(--typography-paragraph-body-font-size);
-  letter-spacing: var(--typography-paragraph-body-letter-spacing);
-  font-weight: var(--typography-paragraph-body-font-weight);
-  line-height: var(--typography-paragraph-body-line-height);
-  color: var(--color-purple-800);
-  padding: var(--spacing-6) var(--spacing-8);
-  border: var(--border-focus-ring-border-width) var(--border-focus-ring-border-style) transparent;
-  border-radius: 4px;
-  margin-inline: var(--spacing-6);
-  text-decoration: none;
-  cursor: pointer;
-}
+@layer kz-components {
+  .item {
+    display: block;
+    font-family: var(--typography-paragraph-body-font-family);
+    font-size: var(--typography-paragraph-body-font-size);
+    letter-spacing: var(--typography-paragraph-body-letter-spacing);
+    font-weight: var(--typography-paragraph-body-font-weight);
+    line-height: var(--typography-paragraph-body-line-height);
+    color: var(--color-purple-800);
+    padding: var(--spacing-6) var(--spacing-8);
+    border: var(--border-focus-ring-border-width) var(--border-focus-ring-border-style) transparent;
+    border-radius: 4px;
+    margin-inline: var(--spacing-6);
+    text-decoration: none;
+    cursor: pointer;
+  }
 
-.flexWrapper {
-  display: flex;
-  gap: 0 var(--spacing-8);
-  align-items: center;
-}
+  .flexWrapper {
+    display: flex;
+    gap: 0 var(--spacing-8);
+    align-items: center;
+  }
 
-.iconWrapper {
-  flex-shrink: 0;
-  display: flex;
-  align-items: center;
-}
+  .iconWrapper {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+  }
 
-.item:focus {
-  outline: none;
-}
+  .item:focus {
+    outline: none;
+  }
 
-.item[data-hovered],
-.item[data-focus-visible] {
-  background-color: var(--color-blue-100);
-  color: var(--color-blue-500);
-}
+  .item[data-hovered],
+  .item[data-focus-visible] {
+    background-color: var(--color-blue-100);
+    color: var(--color-blue-500);
+  }
 
-.item[data-focus-visible] {
-  outline: var(--border-focus-ring-border-width) var(--border-focus-ring-border-style)
-    var(--color-blue-500);
-}
+  .item[data-focus-visible] {
+    outline: var(--border-focus-ring-border-width) var(--border-focus-ring-border-style)
+      var(--color-blue-500);
+  }
 
-.item[data-disabled] {
-  opacity: 0.3;
+  .item[data-disabled] {
+    opacity: 0.3;
+  }
 }

package/src/__next__/Menu/_docs/Menu--migration-guide.mdx

@@ -0,0 +1,91 @@
+import { Meta } from '@storybook/blocks'
+
+<Meta title="Components/Menu/Migration guide" />
+
+# Menu migration guide
+
+## Audience
+
+This guide is relevant for Kaizen All-In-One (KAIO) v1 consumers.
+
+## Purpose
+
+This guide provides instructions for migrating menu usage from the `deprecated` (`@kaizen/components`) `Menu` component to the `next` (`@kaizen/components/next`) `Menu` component.
+
+This migration is a prerequisite for [migrating to KAIO v2](/docs/releases-upcoming-major-releases--docs).
+
+## Key API changes
+
+`next/Menu` separates its functionality into the following components:
+
+- `MenuTrigger` wraps the `MenuPopover` component and its trigger element.
+- `MenuPopover` contains a `Menu` component, and controls the popover placement and open and close interactions.
+- `Menu` contains one or more `MenuItem` and `MenuSection` components.
+- `MenuSection` enables menu items to be grouped into sections.
+- `MenuHeader` provides a section's header content.
+- `MenuItem` provides a menu item's content, and handles item selection.
+
+Other notable changes:
+
+- `Menu.align` prop becomes MenuPopover.placement, and values are mapped as follows:
+  - `left` becomes `start`
+  - `right` becomes `end`
+- `Menu.autoHide` prop is retired
+- `Menu.button` prop becomes `MenuTrigger.children`
+  - The trigger element must be a `next/Button`
+- `Menu.dropdownWidth` prop is retired
+- `Menu.portalSelector` prop is retired
+  - Where needed, [PortalProvider](https://react-spectrum.adobe.com/react-aria/PortalProvider.html) can be used to control portalling behaviour
+- `MenuItem.destructive` prop is retired
+  - This change aligns with a broader move towards more judicious use of colour
+- `MenuItem.disabled` prop becomes `MenuItem.isDisabled`
+- `MenuItem.label` prop becomes `MenuItem.children`
+- `MenuItem.onClick` prop becomes `MenuItem.onAction`
+  - React Aria's `Menu` does not expose native click events, e.g. `MenuItem.onAction` cannot call `e.preventDefault()`
+  - See React Aria [Menu documentation](https://react-spectrum.adobe.com/react-aria/Menu.html) for more details on working with `Menu` and `MenuItem` events
+- `MenuList.heading` prop becomes `MenuHeader` in a `MenuSection`
+
+## Migration example
+
+### Before
+
+```tsx
+<Menu button={<Button>Trigger</Button>}>
+  <MenuList>
+    <MenuList heading={<MenuHeading>Section One</MenuHeading>}>
+      <MenuItem onClick={() => alert('1')} label="Item 1" />
+      <MenuItem onClick={() => alert('2')} label="Item 2" />
+    </MenuList>
+    <MenuList heading={<MenuHeading>Section Two</MenuHeading>}>
+      <MenuItem onClick={() => alert('3')} label="Item 3" />
+      <MenuItem onClick={() => alert('4')} label="Item 4" />
+    </MenuList>
+  </MenuList>
+</Menu>
+```
+
+### After
+
+```tsx
+<MenuTrigger>
+  <Button>Trigger</Button>
+  <MenuPopover>
+    <Menu>
+      <MenuSection>
+        <MenuHeader>Section One</MenuHeader>
+        <MenuItem onAction={() => alert('1')}>Item 1</MenuItem>
+        <MenuItem onAction={() => alert('2')}>Item 2</MenuItem>
+      </MenuSection>
+      <MenuSection>
+        <MenuHeader>Section Two</MenuHeader>
+        <MenuItem onAction={() => alert('3')}>Item 3</MenuItem>
+        <MenuItem onAction={() => alert('4')}>Item 4</MenuItem>
+      </MenuSection>
+    </Menu>
+  </MenuPopover>
+</MenuTrigger>
+```
+
+## More information
+
+More information about `next/Menu` can be found at [API Specification](/docs/components-menu-menu-next-api-specification--docs) and [Usage Guidelines](/docs/components-menu-menu-next-usage-guidelines--docs).

package/src/__next__/Select/Select.module.scss

@@ -3,11 +3,13 @@
 @import '~@kaizen/design-tokens/sass/shadow';
 @import '~@kaizen/design-tokens/sass/spacing';
 
-.container {
-  position: relative;
-  width: 100%;
-}
+@layer kz-components {
+  .container {
+    position: relative;
+    width: 100%;
+  }
 
-.notFullWidth {
-  width: 180px;
+  .notFullWidth {
+    width: 180px;
+  }
 }

package/src/__next__/Select/Select.tsx

@@ -25,7 +25,7 @@ import { getDisabledKeysFromItems } from './utils/getDisabledKeysFromItems'
 import { transformSelectItemToCollectionElement } from './utils/transformSelectItemToCollectionElement'
 import styles from './Select.module.scss'
 
-type OmittedAriaSelectProps = 'children' | 'items'
+type OmittedAriaSelectProps = 'children' | 'items' | 'onSelectionChange'
 
 export type SelectProps<Option extends SelectOption = SelectOption> = {
   /**
@@ -70,6 +70,10 @@ export type SelectProps<Option extends SelectOption = SelectOption> = {
    * Use the `labelText` prop to provide a concise name, and the `description` prop for any help text.
    */
   placeholder?: string
+  /**
+   * Handler that is called when the selection changes.
+   */
+  onSelectionChange?: (key: Key) => void
 } & OverrideClassName<Omit<AriaSelectProps<Option>, OmittedAriaSelectProps>>
 
 /**
@@ -93,8 +97,8 @@ export const Select = <Option extends SelectOption = SelectOption>({
   description,
   placeholder = '',
   isDisabled,
-  portalContainerId,
   onSelectionChange,
+  portalContainerId,
   ...restProps
 }: SelectProps<Option>): JSX.Element => {
   const { refs } = useFloating<HTMLButtonElement>()
@@ -182,7 +186,9 @@ export const Select = <Option extends SelectOption = SelectOption>({
         {state.isOpen && (
           <Popover id={popoverId} portalContainer={portalContainer} refs={refs}>
             <SelectProvider<Option> state={state}>
-              <SelectPopoverContents menuProps={menuProps}>{children}</SelectPopoverContents>
+              <SelectPopoverContents menuProps={menuProps} popoverRef={refs.floating}>
+                {children}
+              </SelectPopoverContents>
             </SelectProvider>
           </Popover>
         )}

package/src/__next__/Select/subcomponents/ListBox/ListBox.module.scss

@@ -1,12 +1,14 @@
-.listBox {
-  list-style: none;
-  margin-top: 0;
-  margin-bottom: 0;
-  padding: 0;
-  display: grid;
-  max-height: 22rem;
-}
+@layer kz-components {
+  .listBox {
+    list-style: none;
+    margin-top: 0;
+    margin-bottom: 0;
+    padding: 0;
+    display: grid;
+    max-height: 22rem;
+  }
 
-.listBox:focus-visible {
-  outline: none;
+  .listBox:focus-visible {
+    outline: none;
+  }
 }

package/src/__next__/Select/subcomponents/ListBoxSection/ListBoxSection.module.scss

@@ -1,20 +1,22 @@
 @import '~@kaizen/design-tokens/sass/spacing';
 
-.sectionWrapper {
-  display: flex;
-  flex-direction: column;
+@layer kz-components {
+  .sectionWrapper {
+    display: flex;
+    flex-direction: column;
 
-  &:not(:first-child) {
-    margin-top: $spacing-8;
+    &:not(:first-child) {
+      margin-top: $spacing-8;
+    }
   }
-}
 
-.sectionHeading {
-  padding-inline-start: $spacing-4;
-}
+  .sectionHeading {
+    padding-inline-start: $spacing-4;
+  }
 
-.sectionList {
-  display: flex;
-  flex-direction: column;
-  padding: $spacing-xs 0 0 0;
+  .sectionList {
+    display: flex;
+    flex-direction: column;
+    padding: $spacing-xs 0 0 0;
+  }
 }

package/src/__next__/Select/subcomponents/Option/Option.module.scss

@@ -3,71 +3,73 @@
 @import '~@kaizen/design-tokens/sass/typography';
 @import '~@kaizen/design-tokens/sass/spacing';
 
-$iconAndBadgeHeight: $spacing-md;
+@layer kz-components {
+  $iconAndBadgeHeight: $spacing-md;
 
-.icon {
-  line-height: 1;
-  height: calc(#{$iconAndBadgeHeight} - #{$border-solid-border-width} * 2);
-  width: calc(#{$iconAndBadgeHeight} - #{$border-solid-border-width} * 2);
-  display: inline-flex;
-  justify-content: center;
-  align-items: center;
-}
+  .icon {
+    line-height: 1;
+    height: calc(#{$iconAndBadgeHeight} - #{$border-solid-border-width} * 2);
+    width: calc(#{$iconAndBadgeHeight} - #{$border-solid-border-width} * 2);
+    display: inline-flex;
+    justify-content: center;
+    align-items: center;
+  }
 
-.option {
-  height: fit-content;
-  align-items: center;
-  display: inline-grid;
-  grid-template-columns: auto $spacing-md;
-  gap: $spacing-xs;
-  padding-block: $spacing-8;
-  padding-inline: $spacing-12 $spacing-6;
-  position: relative;
-  font-family: $typography-paragraph-body-font-family;
-  font-size: $typography-paragraph-body-font-size;
-  letter-spacing: $typography-paragraph-body-letter-spacing;
-  font-weight: $typography-paragraph-body-font-weight;
-  line-height: $typography-paragraph-body-line-height;
-  border: $border-solid-border-width $border-solid-border-style;
-  border-color: $border-borderless-border-color;
-  border-radius: 4px;
-  cursor: default;
+  .option {
+    height: fit-content;
+    align-items: center;
+    display: inline-grid;
+    grid-template-columns: auto $spacing-md;
+    gap: $spacing-xs;
+    padding-block: $spacing-8;
+    padding-inline: $spacing-12 $spacing-6;
+    position: relative;
+    font-family: $typography-paragraph-body-font-family;
+    font-size: $typography-paragraph-body-font-size;
+    letter-spacing: $typography-paragraph-body-letter-spacing;
+    font-weight: $typography-paragraph-body-font-weight;
+    line-height: $typography-paragraph-body-line-height;
+    border: $border-solid-border-width $border-solid-border-style;
+    border-color: $border-borderless-border-color;
+    border-radius: 4px;
+    cursor: default;
 
-  &:focus {
-    outline: none;
-  }
+    &:focus {
+      outline: none;
+    }
 
-  &.isFocusVisible {
-    background-color: $color-blue-100;
-    color: $color-blue-500;
-    outline: var(--border-focus-ring-border-width) var(--border-focus-ring-border-style)
-      var(--color-blue-500);
+    &.isFocusVisible {
+      background-color: $color-blue-100;
+      color: $color-blue-500;
+      outline: var(--border-focus-ring-border-width) var(--border-focus-ring-border-style)
+        var(--color-blue-500);
+
+      .icon {
+        color: $color-blue-500;
+      }
+    }
 
-    .icon {
+    &:hover:not(.disabled),
+    &:active:not(.disabled) {
+      background-color: $color-blue-100;
       color: $color-blue-500;
+
+      .icon {
+        color: $color-blue-500;
+      }
     }
   }
 
-  &:hover:not(.disabled),
-  &:active:not(.disabled) {
-    background-color: $color-blue-100;
+  .isSelected {
+    font-weight: $typography-paragraph-bold-font-weight;
     color: $color-blue-500;
 
-    .icon {
+    &.icon {
       color: $color-blue-500;
     }
   }
-}
-
-.isSelected {
-  font-weight: $typography-paragraph-bold-font-weight;
-  color: $color-blue-500;
 
-  &.icon {
-    color: $color-blue-500;
+  .disabled {
+    color: $color-gray-500;
   }
 }
-
-.disabled {
-  color: $color-gray-500;
-}

package/src/__next__/Select/subcomponents/Overlay/Overlay.tsx

@@ -7,11 +7,13 @@ import { type SelectOption } from '../../types'
 
 export type OverlayProps = OverrideClassName<HTMLAttributes<HTMLDivElement>> & {
   children: React.ReactNode
+  popoverRef?: React.RefObject<Element | null>
 }
 
 export const Overlay = <Option extends SelectOption>({
   children,
   classNameOverride,
+  popoverRef,
   ...restProps
 }: OverlayProps): JSX.Element => {
   const { state } = useSelectContext<Option>()
@@ -21,7 +23,7 @@ export const Overlay = <Option extends SelectOption>({
   const overlayRef = React.useRef<HTMLDivElement>(null)
   const { overlayProps } = useOverlay(
     { isDismissable: true, isOpen: state.isOpen, onClose: state.close },
-    overlayRef,
+    popoverRef ?? overlayRef,
   )
 
   // Wrap in <FocusScope> so that focus is restored back to the trigger when the menu is closed
@@ -29,7 +31,7 @@ export const Overlay = <Option extends SelectOption>({
   // In addition, add hidden <DismissButton> components at the start and end of the list
   // to allow screen reader users to dismiss the popup easily.
   return (
-    <div ref={overlayRef} className={classNameOverride} {...overlayProps} {...restProps}>
+    <div className={classNameOverride} {...overlayProps} {...restProps}>
       {/* eslint-disable-next-line jsx-a11y/no-autofocus */}
       <FocusScope autoFocus={false} restoreFocus>
         <DismissButton onDismiss={state.close} />

package/src/__next__/Select/subcomponents/SectionDivider/SectionDivider.module.scss

@@ -1,11 +1,13 @@
 @import '~@kaizen/design-tokens/sass/spacing';
 
-.divider {
-  margin: $spacing-8 0;
+@layer kz-components {
+  .divider {
+    margin: $spacing-8 0;
 
-  &:first-child,
-  &:last-child,
-  & + .divider {
-    display: none;
+    &:first-child,
+    &:last-child,
+    & + .divider {
+      display: none;
+    }
   }
 }

package/src/__next__/Select/subcomponents/SelectPopoverContents/SelectPopoverContents.module.scss

@@ -1,5 +1,7 @@
 @import '~@kaizen/design-tokens/sass/spacing';
 
-.selectPopoverContents {
-  padding: $spacing-12;
+@layer kz-components {
+  .selectPopoverContents {
+    padding: $spacing-12;
+  }
 }

package/src/__next__/Select/subcomponents/SelectPopoverContents/SelectPopoverContents.tsx

@@ -10,11 +10,13 @@ import styles from './SelectPopoverContents.module.scss'
 export type SelectPopoverContentsProps<Option extends SelectOption> = {
   children?: (args: { items: SelectItemNode<Option>[] }) => React.ReactNode
   menuProps: AriaListBoxOptions<SelectItem<Option>>
+  popoverRef?: React.RefObject<Element | null>
 }
 
 export const SelectPopoverContents = <Option extends SelectOption>({
   children,
   menuProps,
+  popoverRef,
 }: SelectPopoverContentsProps<Option>): JSX.Element => {
   const { state } = useSelectContext<Option>()
 
@@ -26,7 +28,7 @@ export const SelectPopoverContents = <Option extends SelectOption>({
 
   return (
     <div className={styles.selectPopoverContents}>
-      <Overlay<Option>>
+      <Overlay<Option> popoverRef={popoverRef}>
         <ListBox<Option> menuProps={menuProps}>
           {children ? children({ items: itemNodes }) : <ListItems<Option> items={itemNodes} />}
         </ListBox>