@itwin/itwinui-react 3.0.0-dev.9 → 3.0.0

package/README.md

@@ -23,7 +23,9 @@
 ## What is iTwinUI-react?
 
 iTwinUI-react is a React component library for [iTwinUI](https://github.com/iTwin/iTwinUI).
-The goal of this package is to provide React components that make it easier to use the styles from [`@itwin/itwinui-css`](https://github.com/iTwin/iTwinUI/tree/main/packages/itwinui-css). Check out the [demo website](https://itwin.github.io/iTwinUI/react) to see the components in action.
+The goal of this package is to provide React components that make it easier to use the styles from [`@itwin/itwinui-css`](https://github.com/iTwin/iTwinUI/tree/main/packages/itwinui-css). Check out the [documentation website](https://itwinui.bentley.com/) to detailed documentation and examples of all components.
+
+🆕 Check out the [v3 migration guide](https://github.com/iTwin/iTwinUI/wiki/iTwinUI-react-v3-migration-guide) if you're upgrading from an older version.
 
 ---
 
@@ -33,10 +35,6 @@ The goal of this package is to provide React components that make it easier to u
 npm install @itwin/itwinui-react
 ```
 
-```
-yarn add @itwin/itwinui-react
-```
-
 ---
 
 ## Setup

package/cjs/core/Alert/Alert.d.ts

@@ -55,7 +55,7 @@ export declare const Alert: PolymorphicForwardRefComponent<"div", AlertOwnProps
     Icon: PolymorphicForwardRefComponent<"span", Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & {
         ref?: ((instance: HTMLSpanElement | null) => void) | React.RefObject<HTMLSpanElement> | null | undefined;
     }, "fill" | "as" | "key" | "size" | keyof React.HTMLAttributes<HTMLSpanElement> | "padded"> & {
-        size?: "small" | "large" | "auto" | "medium" | import("../utils/types.js").AnyString | undefined;
+        size?: "small" | "auto" | "medium" | "large" | import("../utils/types.js").AnyString | undefined;
         fill?: "default" | "informational" | "negative" | "positive" | "warning" | import("../utils/types.js").AnyString | undefined;
         padded?: boolean | undefined;
     } & Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & {

package/cjs/core/Alert/Alert.js

@@ -9,7 +9,8 @@ const tslib_1 = require('tslib');
 const classnames_1 = tslib_1.__importDefault(require('classnames'));
 const React = tslib_1.__importStar(require('react'));
 const index_js_1 = require('../utils/index.js');
-const index_js_2 = require('../Buttons/index.js');
+const IconButton_js_1 = require('../Buttons/IconButton.js');
+const Icon_js_1 = require('../Icon/Icon.js');
 const AlertContext = React.createContext(undefined);
 // ----------------------------------------------------------------------------
 // Alert component
@@ -75,7 +76,7 @@ const AlertIcon = React.forwardRef((props, ref) => {
   const { type } = (0, index_js_1.useSafeContext)(AlertContext);
   const StatusIcon = index_js_1.StatusIconMap[type];
   return React.createElement(
-    index_js_1.Icon,
+    Icon_js_1.Icon,
     { fill: type, ref: ref, ...rest },
     children ?? React.createElement(StatusIcon, null),
   );
@@ -106,7 +107,7 @@ AlertAction.displayName = 'Alert.Action';
 const AlertCloseButton = React.forwardRef((props, ref) => {
   const { children, ...rest } = props;
   return React.createElement(
-    index_js_2.IconButton,
+    IconButton_js_1.IconButton,
     {
       styleType: 'borderless',
       size: 'small',

package/cjs/core/Avatar/Avatar.js

@@ -9,6 +9,7 @@ const tslib_1 = require('tslib');
 const classnames_1 = tslib_1.__importDefault(require('classnames'));
 const React = tslib_1.__importStar(require('react'));
 const index_js_1 = require('../utils/index.js');
+const VisuallyHidden_js_1 = require('../VisuallyHidden/VisuallyHidden.js');
 /**
  * Helper function that returns one of the preset badge color values.
  */
@@ -77,7 +78,7 @@ exports.Avatar = React.forwardRef((props, ref) => {
     image,
     status
       ? React.createElement(
-          index_js_1.VisuallyHidden,
+          VisuallyHidden_js_1.VisuallyHidden,
           null,
           statusTitles[status],
         )

package/cjs/core/Breadcrumbs/Breadcrumbs.js

@@ -9,6 +9,8 @@ const tslib_1 = require('tslib');
 const React = tslib_1.__importStar(require('react'));
 const classnames_1 = tslib_1.__importDefault(require('classnames'));
 const index_js_1 = require('../utils/index.js');
+const Button_js_1 = require('../Buttons/Button.js');
+const logWarningInDev = (0, index_js_1.createWarningLogger)();
 /**
  * A breadcrumb trail is used as a navigational aid to help users keep track
  * of their place in the application. It is often placed before a page's main content.
@@ -104,24 +106,38 @@ const BreadcrumbsComponent = React.forwardRef((props, ref) => {
     ),
   );
 });
+// ----------------------------------------------------------------------------
 const ListItem = ({ item, isActive }) => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let children = item;
+  if (
+    children?.type === 'span' ||
+    children?.type === 'a' ||
+    children?.type === Button_js_1.Button
+  ) {
+    logWarningInDev(
+      'Directly using Button/a/span as Breadcrumbs children is deprecated, please use `Breadcrumbs.Item` instead.',
+    );
+    children = React.createElement(BreadcrumbsItem, { ...children.props });
+  }
   return React.createElement(
     index_js_1.Box,
     { as: 'li', className: 'iui-breadcrumbs-item' },
-    React.isValidElement(item)
-      ? React.cloneElement(item, {
-          'aria-current':
-            item.props['aria-current'] ?? isActive ? 'location' : undefined,
-        })
-      : item,
+    children &&
+      React.cloneElement(children, {
+        'aria-current':
+          children.props['aria-current'] ?? isActive ? 'location' : undefined,
+      }),
   );
 };
+// ----------------------------------------------------------------------------
 const Separator = ({ separator }) =>
   React.createElement(
     index_js_1.Box,
     { as: 'li', className: 'iui-breadcrumbs-separator', 'aria-hidden': true },
     separator ?? React.createElement(index_js_1.SvgChevronRight, null),
   );
+// ----------------------------------------------------------------------------
 const BreadcrumbsItem = React.forwardRef((props, forwardedRef) => {
   const { children: childrenProp, className, ...rest } = props;
   const defaultAs = !!props.href ? 'a' : !!props.onClick ? 'button' : 'span';
@@ -144,6 +160,7 @@ const BreadcrumbsItem = React.forwardRef((props, forwardedRef) => {
   );
 });
 BreadcrumbsItem.displayName = 'Breadcrumbs.Item';
+// ----------------------------------------------------------------------------
 exports.Breadcrumbs = Object.assign(BreadcrumbsComponent, {
   /**
    * Breadcrumbs item subcomponent

package/cjs/core/ButtonGroup/ButtonGroup.js

@@ -48,10 +48,7 @@ exports.ButtonGroup = React.forwardRef((props, ref) => {
     ...rest
   } = props;
   const items = React.useMemo(
-    () =>
-      React.Children.map(children, (child) =>
-        !!child ? React.createElement('div', null, child) : undefined,
-      )?.filter(Boolean) ?? [],
+    () => React.Children.toArray(children).filter(Boolean),
     [children],
   );
   const [overflowRef, visibleCount] = (0, index_js_1.useOverflow)(
@@ -67,14 +64,15 @@ exports.ButtonGroup = React.forwardRef((props, ref) => {
       index_js_1.Box,
       {
         className: (0, classnames_1.default)(
+          'iui-button-group',
           {
-            'iui-button-group': orientation === 'horizontal',
-            'iui-button-group-vertical': orientation === 'vertical',
             'iui-button-group-overflow-x':
               !!overflowButton && orientation === 'horizontal',
           },
           className,
         ),
+        'data-iui-orientation':
+          orientation === 'vertical' ? orientation : undefined,
         ref: refs,
         ...rest,
       },
@@ -91,13 +89,13 @@ exports.ButtonGroup = React.forwardRef((props, ref) => {
           null,
           overflowButton &&
             overflowPlacement === 'start' &&
-            React.createElement('div', null, overflowButton(overflowStart)),
+            overflowButton(overflowStart),
           overflowPlacement === 'start'
             ? items.slice(overflowStart + 1)
             : items.slice(0, Math.max(0, overflowStart)),
           overflowButton &&
             overflowPlacement === 'end' &&
-            React.createElement('div', null, overflowButton(overflowStart)),
+            overflowButton(overflowStart),
         );
       })(),
     ),

package/cjs/core/Buttons/{Button/Button.d.ts → Button.d.ts}

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { ButtonBase } from '../../utils/index.js';
-import type { PolymorphicForwardRefComponent } from '../../utils/index.js';
+import { ButtonBase } from '../utils/index.js';
+import type { PolymorphicForwardRefComponent } from '../utils/index.js';
 export type ButtonProps = {
     /**
      * Modify size of the button.

package/cjs/core/Buttons/{Button/Button.js → Button.js}

@@ -8,7 +8,7 @@ const tslib_1 = require('tslib');
  *--------------------------------------------------------------------------------------------*/
 const classnames_1 = tslib_1.__importDefault(require('classnames'));
 const React = tslib_1.__importStar(require('react'));
-const index_js_1 = require('../../utils/index.js');
+const index_js_1 = require('../utils/index.js');
 /**
  * Generic button component
  * @example

package/{esm/core/Buttons/DropdownButton → cjs/core/Buttons}/DropdownButton.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="react" />
-import type { ButtonProps } from '../Button/Button.js';
-import type { DropdownMenuProps } from '../../DropdownMenu/index.js';
-import type { PolymorphicForwardRefComponent } from '../../utils/index.js';
+import type { ButtonProps } from './Button.js';
+import type { DropdownMenuProps } from '../DropdownMenu/DropdownMenu.js';
+import type { PolymorphicForwardRefComponent } from '../utils/index.js';
 export type DropdownButtonProps = {
     /**
      * Items in the dropdown menu.

package/cjs/core/Buttons/{DropdownButton/DropdownButton.js → DropdownButton.js}

@@ -8,9 +8,9 @@ const tslib_1 = require('tslib');
  *--------------------------------------------------------------------------------------------*/
 const React = tslib_1.__importStar(require('react'));
 const classnames_1 = tslib_1.__importDefault(require('classnames'));
-const index_js_1 = require('../Button/index.js');
-const index_js_2 = require('../../DropdownMenu/index.js');
-const index_js_3 = require('../../utils/index.js');
+const Button_js_1 = require('./Button.js');
+const DropdownMenu_js_1 = require('../DropdownMenu/DropdownMenu.js');
+const index_js_1 = require('../utils/index.js');
 /**
  * Button that opens a DropdownMenu.
  * @example
@@ -32,7 +32,7 @@ exports.DropdownButton = React.forwardRef((props, forwardedRef) => {
   } = props;
   const [isMenuOpen, setIsMenuOpen] = React.useState(false);
   return React.createElement(
-    index_js_2.DropdownMenu,
+    DropdownMenu_js_1.DropdownMenu,
     {
       menuItems: menuItems,
       matchWidth: true,
@@ -44,16 +44,16 @@ exports.DropdownButton = React.forwardRef((props, forwardedRef) => {
       },
     },
     React.createElement(
-      index_js_1.Button,
+      Button_js_1.Button,
       {
         className: (0, classnames_1.default)('iui-button-dropdown', className),
         size: size,
         styleType: styleType,
         endIcon: isMenuOpen
-          ? React.createElement(index_js_3.SvgCaretUpSmall, {
+          ? React.createElement(index_js_1.SvgCaretUpSmall, {
               'aria-hidden': true,
             })
-          : React.createElement(index_js_3.SvgCaretDownSmall, {
+          : React.createElement(index_js_1.SvgCaretDownSmall, {
               'aria-hidden': true,
             }),
         ref: forwardedRef,

package/{esm/core/Buttons/IconButton → cjs/core/Buttons}/IconButton.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import type { ButtonProps } from '../Button/Button.js';
-import type { PolymorphicForwardRefComponent } from '../../utils/index.js';
+import type { ButtonProps } from './Button.js';
+import type { PolymorphicForwardRefComponent } from '../utils/index.js';
 export type IconButtonProps = {
     /**
      * Button gets active style.

package/cjs/core/Buttons/{IconButton/IconButton.js → IconButton.js}

@@ -8,8 +8,9 @@ const tslib_1 = require('tslib');
  *--------------------------------------------------------------------------------------------*/
 const classnames_1 = tslib_1.__importDefault(require('classnames'));
 const React = tslib_1.__importStar(require('react'));
-const index_js_1 = require('../../utils/index.js');
-const Tooltip_js_1 = require('../../Tooltip/Tooltip.js');
+const index_js_1 = require('../utils/index.js');
+const Tooltip_js_1 = require('../Tooltip/Tooltip.js');
+const VisuallyHidden_js_1 = require('../VisuallyHidden/VisuallyHidden.js');
 /**
  * Icon button
  * @example
@@ -52,7 +53,9 @@ exports.IconButton = React.forwardRef((props, ref) => {
       },
       children,
     ),
-    label ? React.createElement(index_js_1.VisuallyHidden, null, label) : null,
+    label
+      ? React.createElement(VisuallyHidden_js_1.VisuallyHidden, null, label)
+      : null,
   );
   return label
     ? React.createElement(

package/{esm/core/Buttons/IdeasButton → cjs/core/Buttons}/IdeasButton.d.ts

@@ -1,4 +1,4 @@
-import type { PolymorphicForwardRefComponent } from '../../utils/index.js';
+import type { PolymorphicForwardRefComponent } from '../utils/index.js';
 type IdeasButtonProps = {
     /**
      * On click handler.

package/cjs/core/Buttons/{IdeasButton/IdeasButton.js → IdeasButton.js}

@@ -7,8 +7,8 @@ const tslib_1 = require('tslib');
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 const React = tslib_1.__importStar(require('react'));
-const index_js_1 = require('../../utils/index.js');
-const index_js_2 = require('../Button/index.js');
+const index_js_1 = require('../utils/index.js');
+const Button_js_1 = require('./Button.js');
 /**
  * Ideas button
  * @example
@@ -17,7 +17,7 @@ const index_js_2 = require('../Button/index.js');
 exports.IdeasButton = React.forwardRef((props, ref) => {
   const { feedbackLabel = 'Feedback', onClick, ...rest } = props;
   return React.createElement(
-    index_js_2.Button,
+    Button_js_1.Button,
     {
       ref: ref,
       'data-iui-variant': 'idea',

package/cjs/core/Buttons/{SplitButton/SplitButton.d.ts → SplitButton.d.ts}

@@ -1,7 +1,7 @@
 import * as React from 'react';
-import type { ButtonProps } from '../Button/Button.js';
-import { IconButton } from '../IconButton/index.js';
-import type { PolymorphicForwardRefComponent, PortalProps } from '../../utils/index.js';
+import type { ButtonProps } from './Button.js';
+import { IconButton } from './IconButton.js';
+import type { PolymorphicForwardRefComponent, PortalProps } from '../utils/index.js';
 import type { Placement } from '@floating-ui/react';
 export type SplitButtonProps = ButtonProps & {
     /**

package/cjs/core/Buttons/{SplitButton/SplitButton.js → SplitButton.js}

@@ -8,10 +8,11 @@ const tslib_1 = require('tslib');
  *--------------------------------------------------------------------------------------------*/
 const classnames_1 = tslib_1.__importDefault(require('classnames'));
 const React = tslib_1.__importStar(require('react'));
-const index_js_1 = require('../Button/index.js');
-const index_js_2 = require('../IconButton/index.js');
-const index_js_3 = require('../../utils/index.js');
-const Menu_js_1 = require('../../Menu/Menu.js');
+const Button_js_1 = require('./Button.js');
+const IconButton_js_1 = require('./IconButton.js');
+const index_js_1 = require('../utils/index.js');
+const Menu_js_1 = require('../Menu/Menu.js');
+const Popover_js_1 = require('../Popover/Popover.js');
 /**
  * Split button component with a DropdownMenu.
  *
@@ -52,15 +53,15 @@ exports.SplitButton = React.forwardRef((props, forwardedRef) => {
     }
     return menuItems;
   }, [menuItems, close]);
-  const popover = (0, index_js_3.usePopover)({
+  const popover = (0, Popover_js_1.usePopover)({
     visible,
     onVisibleChange: (open) => (open ? setVisible(true) : close()),
     placement: menuPlacement,
     matchWidth: true,
   });
-  const labelId = (0, index_js_3.useId)();
+  const labelId = (0, index_js_1.useId)();
   return React.createElement(
-    index_js_3.Box,
+    index_js_1.Box,
     {
       ...wrapperProps,
       ref: popover.refs.setPositionReference,
@@ -73,20 +74,20 @@ exports.SplitButton = React.forwardRef((props, forwardedRef) => {
       ),
     },
     React.createElement(
-      index_js_1.Button,
+      Button_js_1.Button,
       {
         className: className,
         styleType: styleType,
         size: size,
         onClick: onClick,
-        ref: (0, index_js_3.useMergedRefs)(buttonRef, forwardedRef),
+        ref: (0, index_js_1.useMergedRefs)(buttonRef, forwardedRef),
         ...rest,
         labelProps: { id: labelId, ...props.labelProps },
       },
       children,
     ),
     React.createElement(
-      index_js_2.IconButton,
+      IconButton_js_1.IconButton,
       {
         styleType: styleType,
         size: size,
@@ -97,12 +98,12 @@ exports.SplitButton = React.forwardRef((props, forwardedRef) => {
         ...popover.getReferenceProps(menuButtonProps),
       },
       visible
-        ? React.createElement(index_js_3.SvgCaretUpSmall, null)
-        : React.createElement(index_js_3.SvgCaretDownSmall, null),
+        ? React.createElement(index_js_1.SvgCaretUpSmall, null)
+        : React.createElement(index_js_1.SvgCaretDownSmall, null),
     ),
     popover.open &&
       React.createElement(
-        index_js_3.Portal,
+        index_js_1.Portal,
         { portal: portal },
         React.createElement(
           Menu_js_1.Menu,

package/cjs/core/Carousel/Carousel.d.ts

@@ -14,7 +14,8 @@ type CarouselProps = {
 };
 /**
  * The Carousel component consists of a set of slides, normally displayed one at a time. A navigation section is
- * located below the slides, consisting of "dots" and "previous"/"next" buttons, used for changing slides.
+ * shown below the slides, consisting of "dots" and "previous"/"next" buttons, used for changing slides; this navigation
+ * section must be present _before_ the slides in DOM order, even though it is visually shown below the slides.
  *
  * The currently shown slide can also be changed using the left/right arrow keys or by dragging on a touch device.
  *
@@ -22,27 +23,30 @@ type CarouselProps = {
  *
  * @example
  * <Carousel>
+ *   <Carousel.Navigation />
  *   <Carousel.Slider>
  *     <Carousel.Slide>...</Carousel.Slide>
  *     <Carousel.Slide>...</Carousel.Slide>
  *     <Carousel.Slide>...</Carousel.Slide>
  *   </Carousel.Slider>
- *   <Carousel.Navigation />
  * </Carousel>
  */
 export declare const Carousel: PolymorphicForwardRefComponent<"section", CarouselProps> & {
-    Slider: PolymorphicForwardRefComponent<"ol", {}>;
-    Slide: PolymorphicForwardRefComponent<"li", {
+    Slider: PolymorphicForwardRefComponent<"div", {}>;
+    Slide: PolymorphicForwardRefComponent<"div", {
         index?: number | undefined;
     }>;
-    Navigation: PolymorphicForwardRefComponent<"nav", {}> & {
+    /**
+     * Contains the dots and previous/next buttons for navigating the slides. Must be present _before_ the slides in DOM.
+     */
+    Navigation: PolymorphicForwardRefComponent<"div", {}> & {
         PreviousButton: PolymorphicForwardRefComponent<"button", Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
             ref?: ((instance: HTMLButtonElement | null) => void) | React.RefObject<HTMLButtonElement> | null | undefined;
         }, "label" | "as" | "size" | "htmlDisabled" | "styleType" | "isActive" | "iconProps"> & {
             isActive?: boolean | undefined;
             label?: React.ReactNode;
             iconProps?: React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> | undefined;
-        } & Omit<import("../Buttons/Button/Button.js").ButtonProps, "startIcon" | "endIcon" | "labelProps" | "startIconProps" | "endIconProps"> & {
+        } & Omit<import("../Buttons/Button.js").ButtonProps, "startIcon" | "endIcon" | "labelProps" | "startIconProps" | "endIconProps"> & {
             as?: "button" | undefined;
         }>;
         NextButton: PolymorphicForwardRefComponent<"button", Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
@@ -51,10 +55,13 @@ export declare const Carousel: PolymorphicForwardRefComponent<"section", Carouse
             isActive?: boolean | undefined;
             label?: React.ReactNode;
             iconProps?: React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> | undefined;
-        } & Omit<import("../Buttons/Button/Button.js").ButtonProps, "startIcon" | "endIcon" | "labelProps" | "startIconProps" | "endIconProps"> & {
+        } & Omit<import("../Buttons/Button.js").ButtonProps, "startIcon" | "endIcon" | "labelProps" | "startIconProps" | "endIconProps"> & {
             as?: "button" | undefined;
         }>;
     };
+    /**
+     * Contains the dots for activating the slides. Must be present _before_ the slides in DOM.
+     */
     DotsList: PolymorphicForwardRefComponent<"div", {
         length?: number | undefined;
         currentIndex?: number | undefined;

package/cjs/core/Carousel/Carousel.js

@@ -38,42 +38,9 @@ const CarouselComponent = React.forwardRef((props, ref) => {
     scrollToSlide.current(userActiveIndex, {
       instant: justMounted.current,
     });
-    // re-focus the carousel for keyboard nav, but not on first mount
-    // because it shows outline and might interfere with other components
-    if (!justMounted.current) {
-      carouselRef.current?.focus({ preventScroll: true });
-    }
     justMounted.current = false;
   }, [userActiveIndex]);
   const [slideCount, setSlideCount] = React.useState(0);
-  const [keysPressed, setKeysPressed] = React.useState({});
-  const handleKeyDown = (event) => {
-    if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {
-      return;
-    }
-    const key = event.key;
-    if (key === 'ArrowLeft' || key === 'ArrowRight') {
-      setKeysPressed((old) => ({ ...old, [key]: true }));
-    }
-  };
-  const handleKeyUp = (event) => {
-    switch (event.key) {
-      case 'ArrowLeft': {
-        setKeysPressed((old) => ({ ...old, ArrowLeft: false }));
-        const prevIndex = (slideCount + currentIndex - 1) % slideCount;
-        scrollToSlide.current(prevIndex);
-        setCurrentIndex(prevIndex);
-        break;
-      }
-      case 'ArrowRight': {
-        setKeysPressed((old) => ({ ...old, ArrowRight: false }));
-        const nextIndex = (slideCount + currentIndex + 1) % slideCount;
-        scrollToSlide.current(nextIndex);
-        setCurrentIndex(nextIndex);
-        break;
-      }
-    }
-  };
   const userOnSlideChange = (0, index_js_1.useLatestRef)(onSlideChange);
   React.useEffect(() => {
     userOnSlideChange.current?.(currentIndex);
@@ -83,9 +50,6 @@ const CarouselComponent = React.forwardRef((props, ref) => {
     {
       as: 'section',
       'aria-roledescription': 'carousel',
-      tabIndex: 0,
-      onKeyDown: handleKeyDown,
-      onKeyUp: handleKeyUp,
       ref: refs,
       className: (0, classnames_1.default)('iui-carousel', className),
       ...rest,
@@ -99,7 +63,6 @@ const CarouselComponent = React.forwardRef((props, ref) => {
           setCurrentIndex,
           slideCount,
           setSlideCount,
-          keysPressed,
           idPrefix: id,
           isManuallyUpdating,
           scrollToSlide,
@@ -111,7 +74,8 @@ const CarouselComponent = React.forwardRef((props, ref) => {
 });
 /**
  * The Carousel component consists of a set of slides, normally displayed one at a time. A navigation section is
- * located below the slides, consisting of "dots" and "previous"/"next" buttons, used for changing slides.
+ * shown below the slides, consisting of "dots" and "previous"/"next" buttons, used for changing slides; this navigation
+ * section must be present _before_ the slides in DOM order, even though it is visually shown below the slides.
  *
  * The currently shown slide can also be changed using the left/right arrow keys or by dragging on a touch device.
  *
@@ -119,18 +83,24 @@ const CarouselComponent = React.forwardRef((props, ref) => {
  *
  * @example
  * <Carousel>
+ *   <Carousel.Navigation />
  *   <Carousel.Slider>
  *     <Carousel.Slide>...</Carousel.Slide>
  *     <Carousel.Slide>...</Carousel.Slide>
  *     <Carousel.Slide>...</Carousel.Slide>
  *   </Carousel.Slider>
- *   <Carousel.Navigation />
  * </Carousel>
  */
 exports.Carousel = Object.assign(CarouselComponent, {
   Slider: CarouselSlider_js_1.CarouselSlider,
   Slide: CarouselSlide_js_1.CarouselSlide,
+  /**
+   * Contains the dots and previous/next buttons for navigating the slides. Must be present _before_ the slides in DOM.
+   */
   Navigation: CarouselNavigation_js_1.CarouselNavigation,
+  /**
+   * Contains the dots for activating the slides. Must be present _before_ the slides in DOM.
+   */
   DotsList: CarouselDotsList_js_1.CarouselDotsList,
   Dot: CarouselDot_js_1.CarouselDot,
 });

package/cjs/core/Carousel/CarouselContext.d.ts

@@ -16,10 +16,6 @@ export declare const CarouselContext: React.Context<{
      * State updater for slideCount.
      */
     setSlideCount: (length: number | ((old: number) => void)) => void;
-    /**
-     * Stateful value of the left/right arrow keys currently pressed.
-     */
-    keysPressed: Record<string, boolean>;
     /**
      * Prefix used for setting id for internal carousel components.
      */

package/cjs/core/Carousel/CarouselDot.js

@@ -17,7 +17,7 @@ exports.CarouselDot = React.forwardRef((props, ref) => {
   const { isActive, isSmaller, isSmall, className, ...rest } = props;
   return React.createElement(index_js_1.ButtonBase, {
     role: 'tab',
-    tabIndex: -1,
+    tabIndex: isActive ? 0 : -1,
     className: (0, classnames_1.default)(
       'iui-carousel-navigation-dot',
       {

package/cjs/core/Carousel/CarouselDotsList.js

@@ -53,6 +53,7 @@ exports.CarouselDotsList = React.forwardRef((props, ref) => {
         context.setCurrentIndex(index);
         context.scrollToSlide.current(index);
       }
+      listRef.current?.children[index]?.focus();
       onSlideChange?.(index);
     },
     [context, onSlideChange],
@@ -105,13 +106,12 @@ exports.CarouselDotsList = React.forwardRef((props, ref) => {
           index < firstVisibleDotIndex || index > lastVisibleDotIndex;
         return React.createElement(CarouselDot_js_1.CarouselDot, {
           key: index,
-          'aria-label': `Slide ${index}`,
+          'aria-label': `Slide ${index + 1}`,
           isActive: index === currentIndex,
           onClick: () => handleSlideChange(index),
           isSmall: isSecondSmallDot,
           isSmaller: isFirstSmallDot || isClipped,
           id: idPrefix && `${idPrefix}--dot-${index}`,
-          'aria-controls': idPrefix && `${idPrefix}--slide-${index}`,
         });
       });
   }, [
@@ -138,6 +138,27 @@ exports.CarouselDotsList = React.forwardRef((props, ref) => {
       justMounted.current = false;
     }
   }, [currentIndex, firstVisibleDotIndex, slideCount, visibleCount, width]);
+  const handleKeyDown = (event) => {
+    if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {
+      return;
+    }
+    const key = event.key;
+    if (key === 'ArrowLeft' || key === 'ArrowRight') {
+      event.preventDefault();
+    }
+  };
+  const handleKeyUp = (event) => {
+    switch (event.key) {
+      case 'ArrowLeft': {
+        handleSlideChange((slideCount + currentIndex - 1) % slideCount);
+        break;
+      }
+      case 'ArrowRight': {
+        handleSlideChange((slideCount + currentIndex + 1) % slideCount);
+        break;
+      }
+    }
+  };
   return React.createElement(
     React.Fragment,
     null,
@@ -151,6 +172,9 @@ exports.CarouselDotsList = React.forwardRef((props, ref) => {
         role: 'tablist',
         'aria-label': 'Slides',
         ref: refs,
+        onKeyDown: handleKeyDown,
+        onKeyUp: handleKeyUp,
+        tabIndex: -1,
         ...rest,
       },
       children ?? dots,