@kaizen/components 1.79.1 → 1.79.3

package/dist/cjs/src/__next__/Select/Select.cjs

@@ -132,7 +132,8 @@ var Select = function (_a) {
   }, React__default.default.createElement(SelectContext.SelectProvider, {
     state: state
   }, React__default.default.createElement(SelectPopoverContents.SelectPopoverContents, {
-    menuProps: menuProps
+    menuProps: menuProps,
+    popoverRef: refs.floating
   }, children)))), validationMessage && React__default.default.createElement(FieldMessage.FieldMessage, tslib.__assign({}, errorMessageProps, {
     id: validationId,
     message: validationMessage,

package/dist/cjs/src/__next__/Select/subcomponents/Overlay/Overlay.cjs

@@ -14,7 +14,8 @@ var React__default = /*#__PURE__*/_interopDefault(React);
 var Overlay = function (_a) {
   var children = _a.children,
     classNameOverride = _a.classNameOverride,
-    restProps = tslib.__rest(_a, ["children", "classNameOverride"]);
+    popoverRef = _a.popoverRef,
+    restProps = tslib.__rest(_a, ["children", "classNameOverride", "popoverRef"]);
   var state = SelectContext.useSelectContext().state;
   // Handle events that should cause the menu to close,
   // e.g. blur, clicking outside, or pressing the escape key.
@@ -23,13 +24,12 @@ var Overlay = function (_a) {
     isDismissable: true,
     isOpen: state.isOpen,
     onClose: state.close
-  }, overlayRef).overlayProps;
+  }, popoverRef !== null && popoverRef !== void 0 ? popoverRef : overlayRef).overlayProps;
   // Wrap in <FocusScope> so that focus is restored back to the trigger when the menu is closed
   // and auto focus on the first focusable item after loading. (disable eslint no-autofocus error for it)
   // 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 React__default.default.createElement("div", tslib.__assign({
-    ref: overlayRef,
     className: classNameOverride
   }, overlayProps, restProps), React__default.default.createElement(focus.FocusScope, {
     autoFocus: false,

package/dist/cjs/src/__next__/Select/subcomponents/SelectPopoverContents/SelectPopoverContents.cjs

@@ -14,7 +14,8 @@ function _interopDefault(e) {
 var React__default = /*#__PURE__*/_interopDefault(React);
 var SelectPopoverContents = function (_a) {
   var children = _a.children,
-    menuProps = _a.menuProps;
+    menuProps = _a.menuProps,
+    popoverRef = _a.popoverRef;
   var state = SelectContext.useSelectContext().state;
   // The collection structure is set by useSelectState's `children`
   // which we have used a util to ensure the following structure
@@ -23,7 +24,9 @@ var SelectPopoverContents = function (_a) {
   var itemNodes = Array.from(state.collection);
   return React__default.default.createElement("div", {
     className: SelectPopoverContents_module.selectPopoverContents
-  }, React__default.default.createElement(Overlay.Overlay, null, React__default.default.createElement(ListBox.ListBox, {
+  }, React__default.default.createElement(Overlay.Overlay, {
+    popoverRef: popoverRef
+  }, React__default.default.createElement(ListBox.ListBox, {
     menuProps: menuProps
   }, children ? children({
     items: itemNodes

package/dist/cjs/src/__next__/Tabs/subcomponents/TabList/TabList.cjs

@@ -70,7 +70,7 @@ var TabList = function (props) {
       }
       setLeftArrowEnabled(false);
     }, {
-      threshold: 0.75,
+      threshold: 0.8,
       root: containerElement
     });
     firstTabObserver.observe(isRTL$1 ? tabs[tabs.length - 1] : tabs[0]);
@@ -81,7 +81,7 @@ var TabList = function (props) {
       }
       setRightArrowEnabled(false);
     }, {
-      threshold: 0.75,
+      threshold: 0.8,
       root: containerElement
     });
     lastTabObserver.observe(isRTL$1 ? tabs[0] : tabs[tabs.length - 1]);
@@ -89,7 +89,7 @@ var TabList = function (props) {
       firstTabObserver.disconnect();
       lastTabObserver.disconnect();
     };
-  }, [isDocumentReady, containerElement, isRTL$1]);
+  }, [isDocumentReady, containerElement, isRTL$1, tabListContext === null || tabListContext === void 0 ? void 0 : tabListContext.collection.size]);
   React.useEffect(function () {
     var _a;
     if (!isDocumentReady) {

package/dist/esm/src/__next__/Select/Select.mjs

@@ -124,7 +124,8 @@ const Select = /*#__PURE__*/function () {
     }, /*#__PURE__*/React.createElement(SelectProvider, {
       state: state
     }, /*#__PURE__*/React.createElement(SelectPopoverContents, {
-      menuProps: menuProps
+      menuProps: menuProps,
+      popoverRef: refs.floating
     }, children))))), validationMessage && (/*#__PURE__*/React.createElement(FieldMessage, __assign({}, errorMessageProps, {
       id: validationId,
       message: validationMessage,

package/dist/esm/src/__next__/Select/subcomponents/Overlay/Overlay.mjs

@@ -7,7 +7,8 @@ const Overlay = /*#__PURE__*/function () {
   const Overlay = function (_a) {
     var children = _a.children,
       classNameOverride = _a.classNameOverride,
-      restProps = __rest(_a, ["children", "classNameOverride"]);
+      popoverRef = _a.popoverRef,
+      restProps = __rest(_a, ["children", "classNameOverride", "popoverRef"]);
     var state = useSelectContext().state;
     // Handle events that should cause the menu to close,
     // e.g. blur, clicking outside, or pressing the escape key.
@@ -16,13 +17,12 @@ const Overlay = /*#__PURE__*/function () {
       isDismissable: true,
       isOpen: state.isOpen,
       onClose: state.close
-    }, overlayRef).overlayProps;
+    }, popoverRef !== null && popoverRef !== void 0 ? popoverRef : overlayRef).overlayProps;
     // Wrap in <FocusScope> so that focus is restored back to the trigger when the menu is closed
     // and auto focus on the first focusable item after loading. (disable eslint no-autofocus error for it)
     // 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 /*#__PURE__*/React.createElement("div", __assign({
-      ref: overlayRef,
       className: classNameOverride
     }, overlayProps, restProps), /*#__PURE__*/React.createElement(FocusScope, {
       autoFocus: false,

package/dist/esm/src/__next__/Select/subcomponents/SelectPopoverContents/SelectPopoverContents.mjs

@@ -7,7 +7,8 @@ import styles from './SelectPopoverContents.module.scss.mjs';
 const SelectPopoverContents = /*#__PURE__*/function () {
   const SelectPopoverContents = function (_a) {
     var children = _a.children,
-      menuProps = _a.menuProps;
+      menuProps = _a.menuProps,
+      popoverRef = _a.popoverRef;
     var state = useSelectContext().state;
     // The collection structure is set by useSelectState's `children`
     // which we have used a util to ensure the following structure
@@ -16,7 +17,9 @@ const SelectPopoverContents = /*#__PURE__*/function () {
     var itemNodes = Array.from(state.collection);
     return /*#__PURE__*/React.createElement("div", {
       className: styles.selectPopoverContents
-    }, /*#__PURE__*/React.createElement(Overlay, null, /*#__PURE__*/React.createElement(ListBox, {
+    }, /*#__PURE__*/React.createElement(Overlay, {
+      popoverRef: popoverRef
+    }, /*#__PURE__*/React.createElement(ListBox, {
       menuProps: menuProps
     }, children ? children({
       items: itemNodes

package/dist/esm/src/__next__/Tabs/subcomponents/TabList/TabList.mjs

@@ -61,7 +61,7 @@ var TabList = function (props) {
       }
       setLeftArrowEnabled(false);
     }, {
-      threshold: 0.75,
+      threshold: 0.8,
       root: containerElement
     });
     firstTabObserver.observe(isRTL$1 ? tabs[tabs.length - 1] : tabs[0]);
@@ -72,7 +72,7 @@ var TabList = function (props) {
       }
       setRightArrowEnabled(false);
     }, {
-      threshold: 0.75,
+      threshold: 0.8,
       root: containerElement
     });
     lastTabObserver.observe(isRTL$1 ? tabs[0] : tabs[tabs.length - 1]);
@@ -80,7 +80,7 @@ var TabList = function (props) {
       firstTabObserver.disconnect();
       lastTabObserver.disconnect();
     };
-  }, [isDocumentReady, containerElement, isRTL$1]);
+  }, [isDocumentReady, containerElement, isRTL$1, tabListContext === null || tabListContext === void 0 ? void 0 : tabListContext.collection.size]);
   useEffect(function () {
     var _a;
     if (!isDocumentReady) {

package/dist/styles.css

@@ -6329,6 +6329,8 @@
   .GenericModal-module_transitionLayer__zTH-C {
     transition: opacity var(--animation-duration-fast, 300ms) ease-in-out;
     opacity: 1;
+    position: relative;
+    z-index: 1050;
   }
   .GenericModal-module_transitionLayer__zTH-C .GenericModal-module_backdropLayer__RNQ-U {
     /*
@@ -6720,6 +6722,8 @@
   .ConfirmationModal-module_transitionLayer__Ue95T {
     transition: opacity var(--animation-duration-fast, 300ms) ease-in-out;
     opacity: 1;
+    position: relative;
+    z-index: 1050;
   }
   .ConfirmationModal-module_transitionLayer__Ue95T .ConfirmationModal-module_backdropLayer__wvXnl {
     /*
@@ -7070,6 +7074,8 @@
   .ContextModal-module_transitionLayer__IjJem {
     transition: opacity var(--animation-duration-fast, 300ms) ease-in-out;
     opacity: 1;
+    position: relative;
+    z-index: 1050;
   }
   .ContextModal-module_transitionLayer__IjJem .ContextModal-module_backdropLayer__wuj3B {
     /*
@@ -7394,6 +7400,8 @@
   .InputEditModal-module_transitionLayer__1B3VI {
     transition: opacity var(--animation-duration-fast, 300ms) ease-in-out;
     opacity: 1;
+    position: relative;
+    z-index: 1050;
   }
   .InputEditModal-module_transitionLayer__1B3VI .InputEditModal-module_backdropLayer__aVLSb {
     /*

package/dist/types/__next__/Select/subcomponents/Overlay/Overlay.d.ts

@@ -3,8 +3,9 @@ import { type OverrideClassName } from "../../../../types/OverrideClassName";
 import { type SelectOption } from '../../types';
 export type OverlayProps = OverrideClassName<HTMLAttributes<HTMLDivElement>> & {
     children: React.ReactNode;
+    popoverRef?: React.RefObject<Element | null>;
 };
 export declare const Overlay: {
-    <Option extends SelectOption>({ children, classNameOverride, ...restProps }: OverlayProps): JSX.Element;
+    <Option extends SelectOption>({ children, classNameOverride, popoverRef, ...restProps }: OverlayProps): JSX.Element;
     displayName: string;
 };

package/dist/types/__next__/Select/subcomponents/SelectPopoverContents/SelectPopoverContents.d.ts

@@ -6,8 +6,9 @@ export type SelectPopoverContentsProps<Option extends SelectOption> = {
         items: SelectItemNode<Option>[];
     }) => React.ReactNode;
     menuProps: AriaListBoxOptions<SelectItem<Option>>;
+    popoverRef?: React.RefObject<Element | null>;
 };
 export declare const SelectPopoverContents: {
-    <Option extends SelectOption>({ children, menuProps, }: SelectPopoverContentsProps<Option>): JSX.Element;
+    <Option extends SelectOption>({ children, menuProps, popoverRef, }: SelectPopoverContentsProps<Option>): JSX.Element;
     displayName: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "1.79.1",
+  "version": "1.79.3",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",

package/src/Modal/GenericModal/GenericModal.module.scss

@@ -68,6 +68,8 @@
   .transitionLayer {
     transition: opacity $ca-duration-fast ease-in-out;
     opacity: 1;
+    position: relative;
+    z-index: $ca-z-index-modal;
 
     .backdropLayer {
       /*

package/src/Modal/GenericModal/_docs/GenericModal.spec.stories.tsx

@@ -21,7 +21,11 @@ export const TestBase: Story = {
 
     return (
       <>
-        <button type="button" className="border border-gray-500" onClick={() => setIsOpen(true)}>
+        <button
+          type="button"
+          className="border border-gray-500 relative z-10"
+          onClick={() => setIsOpen(true)}
+        >
           Open Modal
         </button>
         <GenericModal
@@ -30,6 +34,7 @@ export const TestBase: Story = {
           onOutsideModalClick={handleDismiss}
           onEscapeKeyup={handleDismiss}
           id="GenericModalTestId"
+          className="will-change-[opacity]"
         >
           <ModalHeader>
             <ModalAccessibleLabel>Test Modal</ModalAccessibleLabel>

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

@@ -1,11 +1,18 @@
-import { Canvas, Meta, Controls, Story } from '@storybook/blocks'
-import { ResourceLinks, KAIOInstallation } from '~storybook/components'
+import { Meta } from '@storybook/blocks'
 
-<Meta title="Components/Button/Migration Guide" />
+<Meta title="Components/Button/Migration guide" />
 
-# Button Migration Guide (next)
+# Button migration guide
 
-This is a short guide to assist in migration from the old to new `Button` and `LinkButton` component.
+## Audience
+
+This guide is relevant for Kaizen All-In-One (KAIO) v1 consumers.
+
+## Purpose
+
+This guide provides instructions for migrating button usage from `deprecated` (`@kaizen/components`) `Button` and `IconButton` components to `next` (`@kaizen/components/next`) `Button` and `LinkButton` components.
+
+This migration is a prerequisite for [migrating to KAIO v2](/docs/releases-upcoming-major-releases--docs).
 
 ## Key API differences
 

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__/Select/Select.tsx

@@ -183,7 +183,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/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/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>

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

@@ -2,9 +2,17 @@ import { Meta } from '@storybook/blocks'
 
 <Meta title="Components/Tabs/Migration guide" />
 
-# Next Tabs migration guide
+# Tabs migration guide
 
-A brief guide on how and why to migrate from Kaizen's current `Tabs` to the `next` release.
+## Audience
+
+This guide is relevant for Kaizen All-In-One (KAIO) v1 consumers.
+
+## Purpose
+
+This guide provides instructions for migrating tabs usage from the `deprecated` (`@kaizen/components`) `Tabs` component to the `next` (`@kaizen/components/next`) `Tabs` component.
+
+This migration is a prerequisite for [migrating to KAIO v2](/docs/releases-upcoming-major-releases--docs).
 
 ## Why the change?
 

package/src/__next__/Tabs/_docs/Tabs.spec.stories.tsx

@@ -1,8 +1,8 @@
-import React from 'react'
+import React, { useState } from 'react'
 import { type Meta, type StoryObj } from '@storybook/react'
-import { expect, userEvent, within } from '@storybook/test'
+import { expect, userEvent, waitFor, within } from '@storybook/test'
 import { Text } from '~components/Text'
-import { Tab, TabList, TabPanel, Tabs } from '../index'
+import { Tab, TabList, TabPanel, Tabs, type Key } from '../index'
 
 const meta = {
   title: 'Components/Tabs/Tabs (next)/Tabs (next) tests',
@@ -116,3 +116,48 @@ export const ArrowsShowingAndHidingRTL: Story = {
     expect(leftArrow).not.toBeInTheDocument()
   },
 }
+
+export const AsyncLoaded: Story = {
+  render: () => {
+    const [selectedKey, setSelectedKey] = useState<Key>(0)
+
+    const [showSecondTab, setShowSecondTab] = React.useState(false)
+    React.useEffect(() => {
+      const timer = setTimeout(() => setShowSecondTab(true), 1000)
+      return () => clearTimeout(timer)
+    }, [])
+    return (
+      <div style={{ maxWidth: '300px' }}>
+        <Tabs selectedKey={selectedKey} onSelectionChange={setSelectedKey}>
+          <TabList aria-label="Tabs" data-testid="sb-arrows">
+            <Tab id="one">Conversation</Tab>
+            {showSecondTab && <Tab id="two">Personal notes</Tab>}
+          </TabList>
+          <TabPanel id="one" className="p-24">
+            <Text variant="body">Content 1</Text>
+          </TabPanel>
+          <TabPanel id="two" className="p-24">
+            <Text variant="body">Content 2</Text>
+          </TabPanel>
+        </Tabs>
+      </div>
+    )
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement.parentElement!)
+    expect(canvas.queryByTestId('kz-tablist-right-arrow')).not.toBeInTheDocument()
+    await waitFor(() => userEvent.click(canvasElement))
+    await new Promise((r) => setTimeout(r, 2000))
+
+    await step('Check if second tab is loaded', async () => {
+      await waitFor(() => {
+        expect(canvas.queryByText('Personal notes')).toBeInTheDocument()
+      })
+
+      await waitFor(async () => {
+        const rightTab = await canvas.findByTestId('sb-arrows-kz-tablist-right-arrow')
+        expect(rightTab).toBeInTheDocument()
+      })
+    })
+  },
+}

package/src/__next__/Tabs/_docs/Tabs.stories.tsx

@@ -66,11 +66,22 @@ export const Playground: Story = {
 }
 
 export const Controlled: Story = {
-  render: (args) => {
+  render: () => {
     const [selectedKey, setSelectedKey] = useState<Key>(0)
     return (
       <>
-        <Tabs {...args} selectedKey={selectedKey} onSelectionChange={setSelectedKey} />
+        <Tabs selectedKey={selectedKey} onSelectionChange={setSelectedKey}>
+          <TabList aria-label="Tabs">
+            <Tab id="one">Tab 1</Tab>
+            <Tab id="two">Tab 2</Tab>
+          </TabList>
+          <TabPanel id="one" className="p-24">
+            <Text variant="body">Content 1</Text>
+          </TabPanel>
+          <TabPanel id="two" className="p-24">
+            <Text variant="body">Content 2</Text>
+          </TabPanel>
+        </Tabs>
         <Button label="Switch to tab 2" onClick={(): void => setSelectedKey('two')} />
       </>
     )

package/src/__next__/Tabs/subcomponents/TabList/TabList.tsx

@@ -75,7 +75,7 @@ export const TabList = (props: TabListProps): JSX.Element => {
         setLeftArrowEnabled(false)
       },
       {
-        threshold: 0.75,
+        threshold: 0.8,
         root: containerElement,
       },
     )
@@ -90,7 +90,7 @@ export const TabList = (props: TabListProps): JSX.Element => {
         setRightArrowEnabled(false)
       },
       {
-        threshold: 0.75,
+        threshold: 0.8,
         root: containerElement,
       },
     )
@@ -100,7 +100,7 @@ export const TabList = (props: TabListProps): JSX.Element => {
       firstTabObserver.disconnect()
       lastTabObserver.disconnect()
     }
-  }, [isDocumentReady, containerElement, isRTL])
+  }, [isDocumentReady, containerElement, isRTL, tabListContext?.collection.size])
 
   useEffect(() => {
     if (!isDocumentReady) {

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

@@ -0,0 +1,62 @@
+import { Meta } from '@storybook/blocks'
+
+<Meta title="Components/Tooltip/Migration guide" />
+
+# Tooltip migration guide
+
+## Audience
+
+This guide is relevant for Kaizen All-In-One (KAIO) v1 consumers.
+
+## Purpose
+
+This guide provides instructions for migrating tooltip usage from the `deprecated` (`@kaizen/components`) `Tooltip` component to the `next` (`@kaizen/components/next`) `Tooltip` component.
+
+This migration is a prerequisite for [migrating to KAIO v2](/docs/releases-upcoming-major-releases--docs).
+
+## Key API changes
+
+The `next` tooltip separates its functionality into two distinct components:
+
+- `TooltipTrigger` component wraps the `Tooltip` component and its trigger element, and controls open and close interactions.
+- `Tooltip` component provides the tooltip's content and controls its placement.
+
+Other notable changes:
+
+- `animationDuration` prop is retired
+- `children` prop becomes `TooltipTrigger.Children`
+- `display` prop is retired
+- `isInitiallyVisible` prop becomes `Tooltip.defaultOpen`
+- `mood` prop is retired
+  - This change aligns with a broader move towards more judicious use of colour
+- `portalSelector` prop is retired
+  - Where needed, [PortalProvider](https://react-spectrum.adobe.com/react-aria/PortalProvider.html) can be used to control portalling behaviour
+- `position` prop becomes `Tooltip.placement`, and values are mapped as follows:
+  - `above` becomes `top`
+  - `below` becomes `bottom`
+  - `left` becomes `start`
+  - `right` becomes `end`
+- `text` prop becomes `Tooltip.Children`
+
+## Migration example
+
+### Before
+
+```tsx
+<Tooltip text="Content" position="above">
+  <Button>Trigger</Button>
+</Tooltip>
+```
+
+### After
+
+```tsx
+<TooltipTrigger>
+  <Button>Trigger</Button>
+  <Tooltip placement="top">Content</Tooltip>
+</TooltipTrigger>
+```
+
+## More information
+
+More information about the `next` `Tooltip` component can be found at [API Specification](/docs/components-tooltip-tooltip-next-api-specification--docs) and [Usage Guidelines](/docs/components-tooltip-tooltip-next-usage-guidelines--docs).