@workday/canvas-kit-preview-react 7.1.5 → 7.2.0-427-next.2

package/form-field/lib/hooks/useFormFieldOrientation.tsx

@@ -1,4 +1,4 @@
-import {StackSpacing, StackProps} from '@workday/canvas-kit-react/layout';
+import {FlexProps} from '@workday/canvas-kit-react/layout';
 import {space} from '@workday/canvas-kit-react/tokens';
 
 /**
@@ -6,21 +6,21 @@ import {space} from '@workday/canvas-kit-react/tokens';
  */
 export const useFormFieldOrientation = (orientation: 'horizontal' | 'vertical') => {
   let layoutProps: {
-    flexDirection: StackProps['flexDirection'];
-    alignItems: StackProps['alignItems'];
-    spacing: StackSpacing;
+    flexDirection: FlexProps['flexDirection'];
+    alignItems: FlexProps['alignItems'];
+    gap: FlexProps['gap'];
   };
 
   if (orientation === 'horizontal') {
     layoutProps = {
       flexDirection: 'row',
-      spacing: space.l,
+      gap: space.l,
       alignItems: 'center',
     };
   } else {
     layoutProps = {
       flexDirection: 'column',
-      spacing: space.xxxs,
+      gap: space.xxxs,
       alignItems: 'flex-start',
     };
   }

package/index.ts

@@ -1,11 +1,10 @@
-export * from './breadcrumbs';
 export * from './color-picker';
 export * from './form-field';
 export * from './menu';
 export * from './pill';
+export * from './segmented-control';
 export * from './select';
 export * from './side-panel';
+export * from './status-indicator';
 export * from './text-area';
 export * from './text-input';
-
-/// <reference types="@types/node" />

package/menu/index.ts

@@ -1,7 +1,2 @@
-import Menu, {MenuProps} from './lib/Menu';
-import MenuItem from './lib/MenuItem';
-
-export {Menu, MenuItem, MenuProps};
-
-export default Menu;
+export * from './lib/Menu';
 export * from './lib/MenuItem';

package/menu/lib/Menu.tsx

@@ -1,23 +1,35 @@
 import * as React from 'react';
 import styled from '@emotion/styled';
 
-import {MenuItemProps} from './MenuItem';
+import {DeprecatedMenuItemProps} from './MenuItem';
 import {Card} from '@workday/canvas-kit-react/card';
 import {commonColors, space, borderRadius} from '@workday/canvas-kit-react/tokens';
 import {hideMouseFocus, GrowthBehavior, generateUniqueId} from '@workday/canvas-kit-react/common';
 
-export interface MenuProps extends GrowthBehavior, React.HTMLAttributes<HTMLUListElement> {
+/**
+ * ### Deprecated Menu
+ *
+ * As of Canvas Kit v8, Menu is being deprecated.
+ * It will be removed in v10. Please see the
+ * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
+ * for more information.
+ */
+export interface DeprecatedMenuProps
+  extends GrowthBehavior,
+    React.HTMLAttributes<HTMLUListElement> {
   /**
-   * The MenuItem children of the Menu (must be at least one). Also accepts other components which share the same interface as `MenuItem`.
+   * The DeprecatedMenuItem children of the DeprecatedMenu (must be at least one). Also accepts other components which share the same interface as `DeprecatedMenuItem`.
    */
-  children?: React.ReactElement<MenuItemProps> | React.ReactElement<MenuItemProps>[];
+  children?:
+    | React.ReactElement<DeprecatedMenuItemProps>
+    | React.ReactElement<DeprecatedMenuItemProps>[];
   /**
-   * If true, set the Menu to the open state. Useful for showing and hiding the Menu from a parent component such as a menu button.
+   * If true, set the DeprecatedMenu to the open state. Useful for showing and hiding the DeprecatedMenu from a parent component such as a menu button.
    * @default true
    */
   isOpen?: boolean;
   /**
-   * The width of the Menu. If no value is provided, the Menu will collapse around its content.
+   * The width of the DeprecatedMenu. If no value is provided, the DeprecatedMenu will collapse around its content.
    */
   width?: number | string;
   /**
@@ -25,7 +37,7 @@ export interface MenuProps extends GrowthBehavior, React.HTMLAttributes<HTMLULis
    */
   onSelect?: () => void;
   /**
-   * The function called when the Menu should close. This is called after a menu item is selected or if the escape shortcut key is used. This will not fire if the menu item sets `shouldClose` to false.
+   * The function called when the DeprecatedMenu should close. This is called after a menu item is selected or if the escape shortcut key is used. This will not fire if the menu item sets `shouldClose` to false.
    */
   onClose?: () => void;
   /**
@@ -33,16 +45,24 @@ export interface MenuProps extends GrowthBehavior, React.HTMLAttributes<HTMLULis
    */
   initialSelectedItem?: number;
   /**
-   * The unique id of the Menu used for ARIA and HTML `id` attributes.
+   * The unique id of the DeprecatedMenu used for ARIA and HTML `id` attributes.
    */
   id?: string;
   /**
-   * The HTML `id` of the element that labels the Menu. Often used with menu buttons.
+   * The HTML `id` of the element that labels the DeprecatedMenu. Often used with menu buttons.
    */
   'aria-labelledby'?: string;
 }
 
-export interface MenuState {
+/**
+ * ### Deprecated Menu State
+ *
+ * As of Canvas Kit v8, Menu is being deprecated.
+ * It will be removed in v10. Please see the
+ * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
+ * for more information.
+ */
+export interface DeprecatedMenuState {
   selectedItemIndex: number;
 }
 
@@ -57,14 +77,29 @@ const List = styled('ul')({
   ...hideMouseFocus,
 });
 
-export default class Menu extends React.Component<MenuProps, MenuState> {
+/**
+ * As of Canvas Kit v8, Menu is being deprecated.
+ * It will be removed in v10. Please see the [upgrade
+ * guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page) for
+ * more information.
+ *
+ * `DeprecatedMenu` renders a styled `<ul role="menu">` element within a {@link Card} and follows
+ * the [Active Menu
+ * pattern](https://www.w3.org/TR/wai-aria-practices/examples/menu-button/menu-button-actions-active-descendant.html)
+ * using `aria-activedescendant`.
+ *
+ * Undocumented props are spread to the underlying `<ul>` element.
+ *
+ * @deprecated
+ */
+export class DeprecatedMenu extends React.Component<DeprecatedMenuProps, DeprecatedMenuState> {
   private id = generateUniqueId();
   private animateId!: number;
 
   private menuRef: React.RefObject<HTMLUListElement>;
   private firstCharacters!: string[];
 
-  constructor(props: MenuProps) {
+  constructor(props: DeprecatedMenuProps) {
     super(props);
     this.menuRef = React.createRef();
 
@@ -79,7 +114,7 @@ export default class Menu extends React.Component<MenuProps, MenuState> {
     };
   }
 
-  componentDidUpdate(prevProps: MenuProps) {
+  componentDidUpdate(prevProps: DeprecatedMenuProps) {
     if (this.props.children !== prevProps.children) {
       this.setFirstCharacters();
       this.setInitialSelectedItem();
@@ -95,6 +130,13 @@ export default class Menu extends React.Component<MenuProps, MenuState> {
   }
 
   componentDidMount() {
+    console.warn(
+      `This component is being deprecated and will be removed in Canvas Kit V9.\n
+      For more information, please see the V8 upgrade guide:\n
+      https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page
+      `
+    );
+
     this.setFirstCharacters();
     this.setInitialSelectedItem();
   }
@@ -119,6 +161,7 @@ export default class Menu extends React.Component<MenuProps, MenuState> {
     } = this.props;
     const {selectedItemIndex} = this.state;
     const cardWidth = grow ? '100%' : width;
+    let interactiveItemIndex: number | null = null;
 
     return (
       <Card display="inline-block" padding={space.zero} width={cardWidth} depth={3}>
@@ -133,17 +176,22 @@ export default class Menu extends React.Component<MenuProps, MenuState> {
             ref={this.menuRef}
             {...elemProps}
           >
-            {React.Children.map(children, (menuItem, index) => {
+            {React.Children.map(children, menuItem => {
               if (!React.isValidElement(menuItem)) {
                 return;
               }
-              const itemId = `${id}-${index}`;
+              let itemId;
+              if (!menuItem.props.isHeader) {
+                interactiveItemIndex = (interactiveItemIndex ?? -1) + 1;
+                itemId = `${id}-${interactiveItemIndex}`;
+              }
               return (
                 <React.Fragment key={itemId}>
                   {React.cloneElement(menuItem, {
                     onClick: (event: React.MouseEvent) => this.handleClick(event, menuItem.props),
                     id: itemId,
-                    isFocused: selectedItemIndex === index,
+                    isFocused:
+                      selectedItemIndex === interactiveItemIndex && !menuItem.props.isHeader,
                   })}
                 </React.Fragment>
               );
@@ -175,9 +223,12 @@ export default class Menu extends React.Component<MenuProps, MenuState> {
     const children = React.Children.toArray(this.props.children);
     let nextSelectedIndex = 0;
     let isShortcut = false;
-    const itemCount = children.length;
-    const firstItem = 0;
-    const lastItem = itemCount - 1;
+    const interactiveItems = children.filter(child => {
+      return !(child as React.ReactElement<DeprecatedMenuItemProps>)?.props?.isHeader;
+    });
+    const interactiveItemCount = interactiveItems.length;
+    const firstIndex = 0;
+    const lastIndex = interactiveItemCount - 1;
 
     if (event.key.length === 1 && event.key.match(/\S/)) {
       let start = this.state.selectedItemIndex + 1;
@@ -197,18 +248,16 @@ export default class Menu extends React.Component<MenuProps, MenuState> {
       switch (event.key) {
         case 'ArrowUp':
         case 'ArrowDown':
-        case 'Down': // IE/Edge specific value
-        case 'Up': // IE/Edge specific value
           const direction = event.key === 'ArrowUp' ? -1 : 1;
           isShortcut = true;
           const nextIndex = this.state.selectedItemIndex + direction;
           nextSelectedIndex =
-            nextIndex < 0 ? lastItem : nextIndex >= itemCount ? firstItem : nextIndex;
+            nextIndex < 0 ? lastIndex : nextIndex >= interactiveItemCount ? firstIndex : nextIndex;
           break;
 
         case 'Home':
         case 'End':
-          const skipTo = event.key === 'Home' ? firstItem : lastItem;
+          const skipTo = event.key === 'Home' ? firstIndex : lastIndex;
           isShortcut = true;
           nextSelectedIndex = skipTo;
           break;
@@ -231,7 +280,9 @@ export default class Menu extends React.Component<MenuProps, MenuState> {
         case ' ':
         case 'Enter':
           nextSelectedIndex = this.state.selectedItemIndex;
-          const child = children[this.state.selectedItemIndex] as React.ReactElement<MenuItemProps>;
+          const child = interactiveItems[this.state.selectedItemIndex] as React.ReactElement<
+            DeprecatedMenuItemProps
+          >;
           this.handleClick(event, child.props);
           isShortcut = true;
           break;
@@ -248,11 +299,11 @@ export default class Menu extends React.Component<MenuProps, MenuState> {
 
   private handleClick = (
     event: React.MouseEvent | React.KeyboardEvent,
-    menuItemProps: MenuItemProps
+    menuItemProps: DeprecatedMenuItemProps
   ): void => {
     /* istanbul ignore next line for coverage */
     if (menuItemProps.isDisabled) {
-      // You should only hit this point if you are using a custom MenuItem implementation.
+      // You should only hit this point if you are using a custom DeprecatedMenuItem implementation.
       return;
     }
     if (menuItemProps.onClick) {
@@ -284,7 +335,7 @@ export default class Menu extends React.Component<MenuProps, MenuState> {
   private setFirstCharacters = (): void => {
     const getFirstCharacter = (child: React.ReactNode): string => {
       let character = '';
-      if (!child || typeof child === 'boolean' || child === {}) {
+      if (!child || typeof child === 'boolean') {
         character = '';
       } else if (typeof child === 'string' || typeof child === 'number') {
         character = child
@@ -308,6 +359,9 @@ export default class Menu extends React.Component<MenuProps, MenuState> {
     };
 
     const firstCharacters = React.Children.map(this.props.children, child => {
+      if ((child as React.ReactElement<DeprecatedMenuItemProps>)?.props?.isHeader) {
+        return;
+      }
       return getFirstCharacter(child);
     });
 

package/menu/lib/MenuItem.tsx

@@ -11,51 +11,64 @@ import {
 import {CanvasSystemIcon} from '@workday/design-assets-types';
 import {SystemIcon, SystemIconProps} from '@workday/canvas-kit-react/icon';
 
-export interface MenuItemProps extends React.LiHTMLAttributes<HTMLLIElement> {
+/**
+ * ### Deprecated Menu Item Props
+ *
+ * As of Canvas Kit v8, Menu is being deprecated.
+ * It will be removed in v10. Please see the
+ * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
+ * for more information.
+ */
+export interface DeprecatedMenuItemProps extends React.LiHTMLAttributes<HTMLLIElement> {
   /**
-   * The function called when the MenuItem is clicked. If the item is a child of the Menu component, this callback will be decorated with the onSelect and onClose Menu callbacks. This callback will not fire if the item is disabled (see below).
+   * The function called when the DeprecatedMenuItem is clicked. If the item is a child of the DeprecatedMenu component, this callback will be decorated with the onSelect and onClose DeprecatedMenu callbacks. This callback will not fire if the item is disabled (see below).
    */
   onClick?: (event: React.MouseEvent) => void;
   /**
-   * The unique id for the MenuItem used for ARIA attributes. If the item is a child of the `Menu` component, this property will be generated and overridden.
+   * The unique id for the DeprecatedMenuItem used for ARIA attributes. If the item is a child of the `DeprecatedMenu` component, this property will be generated and overridden.
    */
   id?: string;
   /**
-   * The icon of the MenuItem. This icon is displayed before what you supplied for the children.
+   * The icon of the DeprecatedMenuItem. This icon is displayed before what you supplied for the children.
    */
   icon?: CanvasSystemIcon;
   /**
-   * The secondary icon of the MenuItem. This icon is displayed after what you supplied for the children.
+   * The secondary icon of the DeprecatedMenuItem. This icon is displayed after what you supplied for the children.
    */
   secondaryIcon?: CanvasSystemIcon;
   /**
-   * If true, render a top border on the MenuItem.
+   * If true, render a top border on the DeprecatedMenuItem.
    * @default false
    */
   hasDivider?: boolean;
   /**
-   * If true, set the MenuItem to the disabled state so it is not clickable.
+   * If true, render a header to group data, this menu item will not be intractable.
+   * @default false
+   */
+  isHeader?: boolean;
+  /**
+   * If true, set the DeprecatedMenuItem to the disabled state so it is not clickable.
    * @default false
    */
   isDisabled?: boolean;
   /**
-   * If true, set the MenuItem to be the currently selected item. If the item is a child of the Menu component, this property will be generated and overridden.
+   * If true, set the DeprecatedMenuItem to be the currently selected item. If the item is a child of the DeprecatedMenu component, this property will be generated and overridden.
    * @default false
    */
   isFocused?: boolean;
   /**
-   * The role of the MenuItem. Use this to override the role of the item (e.g. you can use this element as an option in a Combobox).
+   * The role of the DeprecatedMenuItem. Use this to override the role of the item (e.g. you can use this element as an option in a Combobox).
    * @default menuItem
    */
   role?: string;
   /**
-   * If true, allow the onClose Menu callback to be fired after the MenuItem has been clicked.
+   * If true, allow the onClose DeprecatedMenu callback to be fired after the DeprecatedMenuItem has been clicked.
    * @default true
    */
   shouldClose?: boolean;
 }
 
-const Item = styled('li')<Pick<MenuItemProps, 'isDisabled' | 'isFocused'>>(
+const Item = styled('li')<Pick<DeprecatedMenuItemProps, 'isDisabled' | 'isFocused' | 'isHeader'>>(
   {
     ...type.levels.subtext.large,
     padding: `${space.xxs} ${space.s}`,
@@ -71,6 +84,9 @@ const Item = styled('li')<Pick<MenuItemProps, 'isDisabled' | 'isFocused'>>(
       outline: 'none',
     },
   },
+  ({isHeader}) => {
+    return {pointerEvents: isHeader ? 'none' : 'all'};
+  },
   ({isFocused, isDisabled}) => {
     if (!isFocused && !isDisabled) {
       return {
@@ -237,10 +253,37 @@ const scrollIntoViewIfNeeded = (elem: HTMLElement, centerIfNeeded = true): void
   }
 };
 
-class MenuItem extends React.Component<MenuItemProps> {
+/**
+ * `DeprecatedMenuItem` renders an `<li>` element with the correct attributes to ensure it is
+ * accessible. If you choose to implement your own custom menu items, be sure to use semantic `<li>`
+ * elements with the following attributes:
+ *
+ * - `role="menuitem"`
+ * - `tabindex={-1}`
+ * - `id`s following this pattern: `${MenuId}-${index}`
+ *
+ * As of Canvas Kit v8, Menu is being deprecated.
+ * It will be removed in v10. Please see the [upgrade
+ * guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page) for
+ * more information.
+ *
+ * Undocumented props are spread to the underlying `<li>` element.
+ *
+ * @deprecated
+ */
+export class DeprecatedMenuItem extends React.Component<DeprecatedMenuItemProps> {
   ref = React.createRef<HTMLLIElement>();
 
-  componentDidUpdate = (prevProps: MenuItemProps) => {
+  componentDidMount() {
+    console.warn(
+      `This component is being deprecated and will be removed in Canvas Kit V9.\n
+      For more information, please see the V8 upgrade guide:\n
+      https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page
+      `
+    );
+  }
+
+  componentDidUpdate = (prevProps: DeprecatedMenuItemProps) => {
     if (!prevProps.isFocused && this.props.isFocused) {
       if (this.ref.current) {
         scrollIntoViewIfNeeded(this.ref.current);
@@ -248,7 +291,7 @@ class MenuItem extends React.Component<MenuItemProps> {
     }
   };
 
-  render(): React.ReactNode {
+  render() {
     const {
       onClick,
       children,
@@ -258,6 +301,7 @@ class MenuItem extends React.Component<MenuItemProps> {
       hasDivider,
       isDisabled,
       isFocused,
+      isHeader,
       role,
       ...elemProps
     } = this.props;
@@ -267,16 +311,18 @@ class MenuItem extends React.Component<MenuItemProps> {
 
     return (
       <>
-        {hasDivider && <Divider />}
+        {hasDivider && <Divider aria-hidden="true" />}
         <Item
           ref={this.ref}
           tabIndex={-1}
           id={id}
-          role={role}
+          role={isHeader ? 'presentation' : role}
+          aria-hidden={isHeader ? true : undefined}
           onClick={this.handleClick}
           aria-disabled={isDisabled ? true : undefined}
           isDisabled={!!isDisabled}
           isFocused={!!isFocused}
+          isHeader={!!isHeader}
           {...elemProps}
         >
           {icon && iconProps && <StyledSystemIcon {...iconProps} />}
@@ -306,9 +352,7 @@ class MenuItem extends React.Component<MenuItemProps> {
  */
 // TODO: Remove this ts-ignore when we convert to a functional component
 // @ts-ignore
-MenuItem.defaultProps = {
+DeprecatedMenuItem.defaultProps = {
   shouldClose: true,
   role: 'menuitem',
 };
-
-export default MenuItem;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-preview-react",
-  "version": "7.1.5",
+  "version": "7.2.0-427-next.2+2c79134a",
   "description": "Canvas Kit Preview is made up of components that have the full design and a11y review, are part of the DS ecosystem and are approved for use in product. The API's could be subject to change, but not without strong communication and migration strategies.",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -41,20 +41,20 @@
     "workday"
   ],
   "peerDependencies": {
-    "react": "^16.8 || ^17.0"
+    "react": ">=16.14"
   },
   "dependencies": {
     "@emotion/react": "^11.7.1",
     "@emotion/styled": "^11.6.0",
-    "@workday/canvas-kit-react": "^7.1.5",
+    "@workday/canvas-kit-react": "^7.2.0-427-next.2+2c79134a",
     "@workday/canvas-system-icons-web": "^3.0.0",
     "@workday/design-assets-types": "^0.2.8"
   },
   "devDependencies": {
     "@workday/canvas-accent-icons-web": "^3.0.0",
-    "@workday/canvas-kit-labs-react": "^7.1.5",
     "formik": "^2.2.9",
-    "yup": "^0.31.1"
+    "react-hook-form": "7.36.1",
+    "yup": "^0.32.11"
   },
-  "gitHead": "ee9ea420cc931e30280810b0268a6861d022d2f3"
+  "gitHead": "2c79134aa48ef0efde9cdf883b529b8157337a28"
 }

package/pill/lib/Pill.tsx

@@ -9,7 +9,7 @@ import {
   styled,
   StyledType,
 } from '@workday/canvas-kit-react/common';
-import {BoxProps, boxStyleFn, HStack, Stack} from '@workday/canvas-kit-react/layout';
+import {BoxProps, boxStyleFn, Flex} from '@workday/canvas-kit-react/layout';
 import {borderRadius, colors, space, type} from '@workday/canvas-kit-react/tokens';
 
 import {usePillModel} from './usePillModel';
@@ -160,14 +160,113 @@ const StyledNonInteractivePill = styled(StyledBasePill)<StyledType>({
   position: 'relative',
 });
 
+/**
+ * By default, a `Pill` renders an interactive element that accepts subcomponents. By "interactive"
+ * we mean that the Pill container is a focusable element (a `<button>`). All leading elements
+ * (icons or avatars) are intended to be descriptive, helping support the label. They should not
+ * receive focus.
+ *
+ * `Pill` is the container component. It also provides a React context model for its subcomponents.
+ * Based on the `variant` prop this component will render different styled `Pill`s.
+ *
+ * Example of read only:
+ *
+ * ```tsx
+ * <Pill variant="readOnly">This is a read only</Pill>
+ * ```
+ *
+ * Example of interactive:
+ *
+ * ```tsx
+ * <Pill onClick={() => console.log('clicked')}>
+ *   <Pill.Avatar /> Regina Skeltor
+ * </Pill>
+ * ```
+ *
+ * Example of removable:
+ *
+ * ```tsx
+ * <Pill variant="removable">
+ *   <Pill.Avatar /> Regina Skeltor
+ *   <Pill.IconButton onClick={() => console.log('clicked')} />
+ * </Pill>
+ * ```
+ *
+ * If you set the `Pill` `variant` to `removable`, it will render a `<span>` element. You can then
+ * provide a `Pill.IconButton` that acts as the focus target. This creates a smaller, more
+ * intentional click target that prevents users from accidentally deleting an item.
+ *
+ * ```tsx
+ * <Pill variant="removable">
+ *   Shoes
+ *   <Pill.IconButton onClick={() => console.log('handle remove')} />
+ * </Pill>
+ * ```
+ */
 export const Pill = createContainer('button')({
+  displayName: 'Pill',
   modelHook: usePillModel,
   subComponents: {
-    Icon: PillIcon,
+    /**
+     * This component renders an avatar. It supports all props of the `Avatar` component.
+     *
+     * ```tsx
+     * <Pill variant="removable">
+     *   <Pill.Avatar url={avatarUrl} />
+     *   Regina Skeltor
+     *   <Pill.IconButton onClick={() => console.log('handle remove')} />
+     * </Pill>
+     * ```
+     */
     Avatar: PillAvatar,
+    /**
+     * This component renders its `children` as the count.
+     *
+     * ```tsx
+     * <Pill onClick={() => console.warn('clicked')}>
+     *   Shoes
+     *   <Pill.Count>30</Pill.Count>
+     * </Pill>
+     * ```
+     */
     Count: PillCount,
-    Label: PillLabel,
+    /**
+     * This component renders an `icon`. It not be used with the `default` styling – not `readOnly`
+     * or `removable` variants. By default it renders a `plusIcon` but it can be overridden by
+     * providing an icon to the `icon` prop.
+     *
+     * ```tsx
+     * <Pill onClick={() => console.warn('clicked')}>
+     *   <Pill.Icon />
+     *   <Pill.Label>Regina Skeltor</Pill.Label>
+     * </Pill>
+     * ```
+     */
+    Icon: PillIcon,
+    /**
+     * This component renders a custom icon button. It is only intended to be used with the
+     * `removable` variant. By default, it renders a `xSmallIcon` but can be overridden by providing
+     * an icon to the `icon` prop.
+     *
+     * ```tsx
+     * <Pill variant="removable">
+     *   Pink Shirts
+     *   <Pill.IconButton onClick={() => console.warn('clicked')} />
+     * </Pill>
+     * ```
+     */
     IconButton: PillIconButton,
+    /**
+     * This component renders a `<span>` that automatically handles overflow by rendering a tooltip.
+     * There's no need to use this component directly since the overflow is handled for you automatically.
+     *
+     * ```tsx
+     * <Pill variant="readOnly">
+     *   <Pill.Label>Read-only</Pill.Label>
+     * </Pill>
+     * ```
+     */
+    Label: PillLabel,
   },
 })<PillProps>(({variant = 'default', maxWidth, ...elemProps}, Element, model) => {
   return (
@@ -190,18 +289,18 @@ export const Pill = createContainer('button')({
           {...elemProps}
           disabled={model.state.disabled}
         >
-          <HStack spacing="xxxs" display="inline-flex" alignItems="center">
+          <Flex gap="xxxs" display="inline-flex" alignItems="center">
             {React.Children.map(elemProps.children, (child, index) => {
               if (typeof child === 'string') {
                 return <PillLabel key={index}>{child}</PillLabel>;
               }
               return (
-                <Stack.Item key={index} display="inline-flex">
+                <Flex.Item key={index} display="inline-flex">
                   {child}
-                </Stack.Item>
+                </Flex.Item>
               );
             })}
-          </HStack>
+          </Flex>
         </StyledBasePill>
       )}
       {variant === 'removable' && (
@@ -211,14 +310,14 @@ export const Pill = createContainer('button')({
           variant={variant}
           {...elemProps}
         >
-          <HStack spacing="xxxs" display="inline-flex" alignItems="center" justifyContent="center">
+          <Flex gap="xxxs" display="inline-flex" alignItems="center" justifyContent="center">
             {React.Children.map(elemProps.children, (child, index) => {
               if (typeof child === 'string') {
                 return <PillLabel key={index}>{child}</PillLabel>;
               }
-              return <Stack.Item key={index}>{child}</Stack.Item>;
+              return <Flex.Item key={index}>{child}</Flex.Item>;
             })}
-          </HStack>
+          </Flex>
         </StyledNonInteractivePill>
       )}
     </>