@carbon/react 1.53.0 → 1.54.0-rc.0

package/es/components/Pagination/Pagination.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Copyright IBM Corp. 2016, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+type ExcludedAttributes = 'id' | 'onChange';
+export interface PaginationPageSize {
+    text: string;
+    value: number;
+}
+export interface PaginationProps extends Omit<React.HTMLAttributes<HTMLDivElement>, ExcludedAttributes> {
+    /**
+     * The description for the backward icon.
+     */
+    backwardText?: string;
+    /**
+     * The CSS class names.
+     */
+    className?: string;
+    /**
+     * `true` if the backward/forward buttons, as well as the page select elements,  should be disabled.
+     */
+    disabled?: boolean;
+    /**
+     * The description for the forward icon.
+     */
+    forwardText?: string;
+    /**
+     * The unique ID of this component instance.
+     */
+    id?: string | number;
+    /**
+     * `true` if the current page should be the last page.
+     */
+    isLastPage?: boolean;
+    /**
+     * The function returning a translatable text showing where the current page is,
+     * in a manner of the range of items.
+     */
+    itemRangeText?: (min: number, max: number, total: number) => string;
+    /**
+     * A variant of `itemRangeText`, used if the total number of items is unknown.
+     */
+    itemText?: (min: number, max: number) => string;
+    /**
+     * The translatable text indicating the number of items per page.
+     */
+    itemsPerPageText?: string;
+    /**
+     * The callback function called when the current page changes.
+     */
+    onChange?: (data: {
+        page: number;
+        pageSize: number;
+        ref?: React.RefObject<any>;
+    }) => void;
+    /**
+     * The current page.
+     */
+    page?: number;
+    /**
+     * `true` if the select box to change the page should be disabled.
+     */
+    pageInputDisabled?: boolean;
+    pageNumberText?: string;
+    /**
+     * A function returning PII showing where the current page is.
+     */
+    pageRangeText?: (current: number, total: number) => string;
+    /**
+     * The number dictating how many items a page contains.
+     */
+    pageSize?: number;
+    /**
+     * `true` if the select box to change the items per page should be disabled.
+     */
+    pageSizeInputDisabled?: boolean;
+    /**
+     * The choices for `pageSize`.
+     */
+    pageSizes: number[] | PaginationPageSize[];
+    /**
+     * The translatable text showing the current page.
+     */
+    pageText?: (page: number, pagesUnknown?: boolean) => string;
+    /**
+     * `true` if the total number of items is unknown.
+     */
+    pagesUnknown?: boolean;
+    /**
+     * Specify the size of the Pagination.
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * The total number of items.
+     */
+    totalItems?: number;
+}
+declare const Pagination: React.ForwardRefExoticComponent<PaginationProps & React.RefAttributes<HTMLDivElement>>;
+export default Pagination;

package/es/components/Pagination/Pagination.js

@@ -27,7 +27,7 @@ function mapPageSizesToObject(sizes) {
 }
 function renderSelectItems(total) {
   let counter = 1;
-  let itemArr = [];
+  const itemArr = [];
   while (counter <= total) {
     itemArr.push( /*#__PURE__*/React__default.createElement(SelectItem, {
       key: counter,
@@ -52,7 +52,7 @@ function getPageSize(pageSizes, pageSize) {
 const Pagination = /*#__PURE__*/React__default.forwardRef(function Pagination(_ref, ref) {
   let {
     backwardText = 'Previous page',
-    className: customClassName,
+    className: customClassName = '',
     disabled = false,
     forwardText = 'Next page',
     id,
@@ -71,11 +71,11 @@ const Pagination = /*#__PURE__*/React__default.forwardRef(function Pagination(_r
     pageText = (page, pagesUnknown) => `page ${pagesUnknown ? '' : page}`,
     pagesUnknown = false,
     size = 'md',
-    totalItems,
+    totalItems = 1,
     ...rest
   } = _ref;
   const prefix = usePrefix();
-  const inputId = useFallbackId(id);
+  const inputId = useFallbackId(id?.toString());
   const backBtnRef = useRef(null);
   const forwardBtnRef = useRef(null);
   const [pageSizes, setPageSizes] = useState(() => {
@@ -163,14 +163,14 @@ const Pagination = /*#__PURE__*/React__default.forwardRef(function Pagination(_r
     // the icon button becomes disabled and the focus shifts to `main`
     // this presents an a11y problem for keyboard & screen reader users
     // instead, we want the focus to shift to the other pagination btn
-    if (nextPage === totalPages) {
+    if (nextPage === totalPages && backBtnRef?.current) {
       backBtnRef.current.focus();
     }
     if (onChange) {
       onChange({
         page: nextPage,
         pageSize,
-        backBtnRef
+        ref: backBtnRef
       });
     }
   }
@@ -182,14 +182,14 @@ const Pagination = /*#__PURE__*/React__default.forwardRef(function Pagination(_r
     // the icon button becomes disabled and the focus shifts to `main`
     // this presents an a11y problem for keyboard & screen reader users
     // instead, we want the focus to shift to the other pagination btn
-    if (nextPage === 1) {
+    if (nextPage === 1 && forwardBtnRef?.current) {
       forwardBtnRef.current.focus();
     }
     if (onChange) {
       onChange({
         page: nextPage,
         pageSize,
-        forwardBtnRef
+        ref: forwardBtnRef
       });
     }
   }
@@ -320,10 +320,10 @@ Pagination.propTypes = {
   /**
    * The choices for `pageSize`.
    */
-  pageSizes: PropTypes.oneOfType([PropTypes.arrayOf(PropTypes.number), PropTypes.arrayOf(PropTypes.shape({
-    text: PropTypes.text,
-    value: PropTypes.number
-  }))]).isRequired,
+  pageSizes: PropTypes.oneOfType([PropTypes.arrayOf(PropTypes.number.isRequired), PropTypes.arrayOf(PropTypes.shape({
+    text: PropTypes.string.isRequired,
+    value: PropTypes.number.isRequired
+  }).isRequired)]).isRequired,
   /**
    * The translatable text showing the current page.
    */
@@ -341,6 +341,5 @@ Pagination.propTypes = {
    */
   totalItems: PropTypes.number
 };
-var Pagination$1 = Pagination;
 
-export { Pagination$1 as default };
+export { Pagination as default };

package/es/components/Pagination/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright IBM Corp. 2016, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import Pagination from './Pagination';
+export * from './Pagination.Skeleton';
+export default Pagination;
+export { Pagination };

package/es/components/Popover/index.d.ts

@@ -6,7 +6,7 @@
  */
 import React, { type ForwardedRef, type WeakValidationMap, type ElementType } from 'react';
 import { type PolymorphicProps } from '../../types/common';
-export type PopoverAlignment = 'top' | 'top-left' | 'top-right' | 'bottom' | 'bottom-left' | 'bottom-right' | 'left' | 'left-bottom' | 'left-top' | 'right' | 'right-bottom' | 'right-top';
+export type PopoverAlignment = 'top' | 'top-left' | 'top-right' | 'bottom' | 'bottom-left' | 'bottom-right' | 'left' | 'left-bottom' | 'left-top' | 'right' | 'right-bottom' | 'right-top' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-end' | 'left-start' | 'right-end' | 'right-start';
 interface PopoverBaseProps {
     /**
      * Specify how the popover should align with the trigger element

package/es/components/Popover/index.js

@@ -8,21 +8,27 @@
 import { extends as _extends } from '../../_virtual/_rollupPluginBabelHelpers.js';
 import cx from 'classnames';
 import PropTypes from 'prop-types';
-import React__default, { useRef, useMemo, useState } from 'react';
+import React__default, { useRef, useMemo, useEffect } from 'react';
 import useIsomorphicEffect from '../../internal/useIsomorphicEffect.js';
 import { useMergedRefs } from '../../internal/useMergedRefs.js';
 import { usePrefix } from '../../internal/usePrefix.js';
 import { useWindowEvent } from '../../internal/useEvent.js';
+import { mapPopoverAlignProp } from '../../tools/createPropAdapter.js';
+import { useFloating, offset, flip, arrow, autoUpdate } from '@floating-ui/react';
 
 const PopoverContext = /*#__PURE__*/React__default.createContext({
-  floating: {
+  setFloating: {
     current: null
-  }
+  },
+  caretRef: {
+    current: null
+  },
+  autoAlign: null
 });
 const Popover = /*#__PURE__*/React__default.forwardRef(function PopoverRenderFunction(_ref, forwardRef) {
   let {
     isTabTip,
-    align = isTabTip ? 'bottom-left' : 'bottom',
+    align: initialAlign = isTabTip ? 'bottom-start' : 'bottom',
     as: BaseComponent = 'span',
     autoAlign = false,
     caret = isTabTip ? false : true,
@@ -36,7 +42,9 @@ const Popover = /*#__PURE__*/React__default.forwardRef(function PopoverRenderFun
   } = _ref;
   const prefix = usePrefix();
   const floating = useRef(null);
+  const caretRef = useRef(null);
   const popover = useRef(null);
+  let align = mapPopoverAlignProp(initialAlign);
 
   // If the `Popover` is the last focusable item in the tab order, it should also close when the browser window loses focus  (#12922)
   useWindowEvent('blur', () => {
@@ -49,124 +57,150 @@ const Popover = /*#__PURE__*/React__default.forwardRef(function PopoverRenderFun
       onRequestClose?.();
     }
   });
+
+  // Slug styling places a border around the popover content so the caret
+  // needs to be placed 1px further outside the popover content. To do so,
+  // we look to see if any of the children has a className containing "slug"
+  const initialCaretHeight = React__default.Children.toArray(children).some(x => {
+    return x?.props?.className?.includes('slug');
+  }) ? 7 : 6;
+  // These defaults match the defaults defined in packages/styles/scss/components/popover/_popover.scss
+  const popoverDimensions = useRef({
+    offset: 10,
+    caretHeight: initialCaretHeight
+  });
+  useIsomorphicEffect(() => {
+    // The popover is only offset when a caret is present. Technically, the custom properties
+    // accessed below can be set by a user even if caret=false, but doing so does not follow
+    // the design specification for Popover.
+    if (caret && popover.current) {
+      // Gather the dimensions of the caret and prefer the values set via custom properties.
+      // If a value is not set via a custom property, provide a default value that matches the
+      // default values defined in the sass style file
+      const getStyle = window.getComputedStyle(popover.current, null);
+      const offsetProperty = getStyle.getPropertyValue('--cds-popover-offset');
+      const caretProperty = getStyle.getPropertyValue('--cds-popover-caret-height');
+
+      // Handle if the property values are in px or rem.
+      // We want to store just the base number value without a unit suffix
+      if (offsetProperty) {
+        popoverDimensions.current.offset = offsetProperty.includes('px') ? Number(offsetProperty.split('px', 1)[0]) * 1 : Number(offsetProperty.split('rem', 1)[0]) * 16;
+      }
+      if (caretProperty) {
+        popoverDimensions.current.caretHeight = caretProperty.includes('px') ? Number(caretProperty.split('px', 1)[0]) * 1 : Number(caretProperty.split('rem', 1)[0]) * 16;
+      }
+    }
+  });
+  const {
+    refs,
+    floatingStyles,
+    placement,
+    middlewareData
+  } = useFloating(autoAlign ? {
+    placement: align,
+    // The floating element is positioned relative to its nearest
+    // containing block (usually the viewport). It will in many cases also
+    // “break” the floating element out of a clipping ancestor.
+    // https://floating-ui.com/docs/misc#clipping
+    strategy: 'fixed',
+    // Middleware order matters, arrow should be last
+    middleware: [offset(!isTabTip ? popoverDimensions?.current?.offset : 0), flip({
+      fallbackAxisSideDirection: 'start'
+    }), arrow({
+      element: caretRef
+    })],
+    whileElementsMounted: autoUpdate
+  } : {} // When autoAlign is turned off, floating-ui will not be used
+  );
+
   const value = useMemo(() => {
     return {
-      floating
+      floating,
+      setFloating: refs.setFloating,
+      caretRef,
+      autoAlign: autoAlign
     };
-  }, []);
+  }, [refs.setFloating, autoAlign]);
   if (isTabTip) {
-    const tabTipAlignments = ['bottom-left', 'bottom-right'];
+    const tabTipAlignments = ['bottom-start', 'bottom-end'];
     if (!tabTipAlignments.includes(align)) {
-      align = 'bottom-left';
+      align = 'bottom-start';
     }
   }
+  useEffect(() => {
+    if (autoAlign) {
+      Object.keys(floatingStyles).forEach(style => {
+        if (refs.floating.current) {
+          refs.floating.current.style[style] = floatingStyles[style];
+        }
+      });
+      if (caret && middlewareData && middlewareData.arrow && caretRef?.current) {
+        const {
+          x,
+          y
+        } = middlewareData.arrow;
+        const staticSide = {
+          top: 'bottom',
+          right: 'left',
+          bottom: 'top',
+          left: 'right'
+        }[placement.split('-')[0]];
+        caretRef.current.style.left = x != null ? `${x}px` : '';
+        caretRef.current.style.top = y != null ? `${y}px` : '';
+
+        // Ensure the static side gets unset when flipping to other placements' axes.
+        caretRef.current.style.right = '';
+        caretRef.current.style.bottom = '';
+        if (staticSide) {
+          caretRef.current.style[staticSide] = `${-popoverDimensions?.current?.caretHeight}px`;
+        }
+      }
+    }
+  }, [floatingStyles, refs.floating, autoAlign, middlewareData, placement, caret]);
   const ref = useMergedRefs([forwardRef, popover]);
-  const [autoAligned, setAutoAligned] = useState(false);
-  const [autoAlignment, setAutoAlignment] = useState(align);
+  const currentAlignment = autoAlign && placement !== align ? placement : align;
   const className = cx({
     [`${prefix}--popover-container`]: true,
     [`${prefix}--popover--caret`]: caret,
     [`${prefix}--popover--drop-shadow`]: dropShadow,
     [`${prefix}--popover--high-contrast`]: highContrast,
     [`${prefix}--popover--open`]: open,
-    [`${prefix}--popover--${autoAlignment}`]: autoAligned && !isTabTip,
-    [`${prefix}--popover--${align}`]: !autoAligned,
+    [`${prefix}--popover--auto-align`]: autoAlign,
+    [`${prefix}--popover--${currentAlignment}`]: true,
     [`${prefix}--popover--tab-tip`]: isTabTip
   }, customClassName);
-  useIsomorphicEffect(() => {
-    if (!open) {
-      return;
-    }
-    if (!autoAlign || isTabTip) {
-      setAutoAligned(false);
-      return;
-    }
-    if (!floating.current) {
-      return;
-    }
-    if (autoAligned === true) {
-      return;
-    }
-    const rect = floating.current.getBoundingClientRect();
-
-    // The conditions, per side, of when the popover is not visible, excluding the popover's internal padding(16)
-    const conditions = {
-      left: rect.x < -16,
-      top: rect.y < -16,
-      right: rect.x + (rect.width - 16) > document.documentElement.clientWidth,
-      bottom: rect.y + (rect.height - 16) > document.documentElement.clientHeight
-    };
-    if (!conditions.left && !conditions.top && !conditions.right && !conditions.bottom) {
-      setAutoAligned(false);
-      return;
-    }
-    const alignments = ['top', 'top-left', 'right-bottom', 'right', 'right-top', 'bottom-left', 'bottom', 'bottom-right', 'left-top', 'left', 'left-bottom', 'top-right'];
-
-    // Creates the prioritized list of options depending on ideal alignment coming from `align`
-    const options = [align];
-    let option = alignments[(alignments.indexOf(align) + 1) % alignments.length];
-    while (option) {
-      if (options.includes(option)) {
-        break;
-      }
-      options.push(option);
-      option = alignments[(alignments.indexOf(option) + 1) % alignments.length];
-    }
-    function isVisible(alignment) {
-      if (!popover.current || !floating.current) {
-        return false;
-      }
-      popover.current.classList.add(`${prefix}--popover--${alignment}`);
-      const rect = floating.current.getBoundingClientRect();
-
-      // Check if popover is not visible to the left of the screen
-      if (rect.x < -16) {
-        popover.current.classList.remove(`${prefix}--popover--${alignment}`);
-        return false;
-      }
-
-      // Check if popover is not visible at the top of the screen
-      if (rect.y < -16) {
-        popover.current.classList.remove(`${prefix}--popover--${alignment}`);
-        return false;
-      }
-
-      // Check if popover is not visible to right of screen
-      if (rect.x + (rect.width - 16) > document.documentElement.clientWidth) {
-        popover.current.classList.remove(`${prefix}--popover--${alignment}`);
-        return false;
-      }
-
-      // Check if popover is not visible to bottom of screen
-      if (rect.y + (rect.height - 16) > document.documentElement.clientHeight) {
-        popover.current.classList.remove(`${prefix}--popover--${alignment}`);
-        return false;
-      }
-      popover.current.classList.remove(`${prefix}--popover--${alignment}`);
-      return true;
-    }
-    let alignment = null;
-    for (let i = 0; i < options.length; i++) {
-      const option = options[i];
-      if (isVisible(option)) {
-        alignment = option;
-        break;
-      }
-    }
-    if (alignment) {
-      setAutoAligned(true);
-      setAutoAlignment(alignment);
-    }
-  }, [autoAligned, align, autoAlign, prefix, open, isTabTip]);
   const mappedChildren = React__default.Children.map(children, child => {
     const item = child;
-    if (item?.type === 'button') {
-      const {
-        className
-      } = item.props;
+    if ((item?.type === 'button' || autoAlign && item?.type?.displayName !== 'PopoverContent' || autoAlign && item?.type?.displayName === 'ToggletipButton') && /*#__PURE__*/React__default.isValidElement(item)) {
+      const className = item?.props?.className;
+      const ref = (item?.props).ref;
       const tabTipClasses = cx(`${prefix}--popover--tab-tip__button`, className);
       return /*#__PURE__*/React__default.cloneElement(item, {
-        className: tabTipClasses
+        className: isTabTip && item?.type === 'button' ? tabTipClasses : className || '',
+        // With cloneElement, if you pass a `ref`, it overrides the original ref.
+        // https://react.dev/reference/react/cloneElement#parameters
+        // The block below works around this and ensures that the original ref is still
+        // called while allowing the floating-ui reference element to be set as well.
+        // `useMergedRefs` can't be used here because hooks can't be called from within a callback.
+        // More here: https://github.com/facebook/react/issues/8873#issuecomment-489579878
+        ref: node => {
+          // For a popover, there isn't an explicit trigger component, it's just the first child that's
+          // passed in which should *not* be PopoverContent.
+          // For a toggletip there is a specific trigger component, ToggletipButton.
+          // In either of these caes we want to set this as the reference node for floating-ui autoAlign
+          // positioning.
+          if (autoAlign && item?.type?.displayName !== 'PopoverContent' || autoAlign && item?.type?.displayName === 'ToggletipButton') {
+            // Set the reference element for floating-ui
+            refs.setReference(node);
+          }
+
+          // Call the original ref, if any
+          if (typeof ref === 'function') {
+            ref(node);
+          } else if (ref !== null && ref !== undefined) {
+            ref.current = node;
+          }
+        }
       });
     } else {
       return item;
@@ -178,7 +212,7 @@ const Popover = /*#__PURE__*/React__default.forwardRef(function PopoverRenderFun
   }, /*#__PURE__*/React__default.createElement(BaseComponentAsAny, _extends({}, rest, {
     className: className,
     ref: ref
-  }), isTabTip ? mappedChildren : children));
+  }), autoAlign || isTabTip ? mappedChildren : children));
 });
 
 // Note: this displayName is temporarily set so that Storybook ArgTable
@@ -190,7 +224,28 @@ Popover.propTypes = {
   /**
    * Specify how the popover should align with the trigger element
    */
-  align: PropTypes.oneOf(['top', 'top-left', 'top-right', 'bottom', 'bottom-left', 'bottom-right', 'left', 'left-bottom', 'left-top', 'right', 'right-bottom', 'right-top']),
+  align: PropTypes.oneOf(['top', 'top-left',
+  // deprecated use top-start instead
+  'top-right',
+  // deprecated use top-end instead
+
+  'bottom', 'bottom-left',
+  // deprecated use bottom-start instead
+  'bottom-right',
+  // deprecated use bottom-end instead
+
+  'left', 'left-bottom',
+  // deprecated use left-end instead
+  'left-top',
+  // deprecated use left-start instead
+
+  'right', 'right-bottom',
+  // deprecated use right-end instead
+  'right-top',
+  // deprecated use right-start instead
+
+  // new values to match floating-ui
+  'top-start', 'top-end', 'bottom-start', 'bottom-end', 'left-end', 'left-start', 'right-end', 'right-start']),
   /**
    * Provide a custom element or component to render the top-level node for the
    * component.
@@ -244,19 +299,31 @@ _ref2, forwardRef) {
   } = _ref2;
   const prefix = usePrefix();
   const {
-    floating
+    setFloating,
+    caretRef,
+    autoAlign
   } = React__default.useContext(PopoverContext);
-  const ref = useMergedRefs([floating, forwardRef]);
+  const ref = useMergedRefs([setFloating, forwardRef]);
   return /*#__PURE__*/React__default.createElement("span", _extends({}, rest, {
     className: `${prefix}--popover`
   }), /*#__PURE__*/React__default.createElement("span", {
     className: cx(`${prefix}--popover-content`, className),
     ref: ref
-  }, children), /*#__PURE__*/React__default.createElement("span", {
-    className: `${prefix}--popover-caret`
+  }, children, autoAlign && /*#__PURE__*/React__default.createElement("span", {
+    className: cx({
+      [`${prefix}--popover-caret`]: true,
+      [`${prefix}--popover--auto-align`]: true
+    }),
+    ref: caretRef
+  })), !autoAlign && /*#__PURE__*/React__default.createElement("span", {
+    className: cx({
+      [`${prefix}--popover-caret`]: true
+    }),
+    ref: caretRef
   }));
 }
 const PopoverContent = /*#__PURE__*/React__default.forwardRef(PopoverContentRenderFunction);
+PopoverContent.displayName = 'PopoverContent';
 PopoverContent.propTypes = {
   /**
    * Provide elements to be rendered inside of the component

package/es/components/RadioTile/RadioTile.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright IBM Corp. 2016, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+export interface RadioTileProps {
+    /**
+     * Specify whether the `RadioTile` should be checked.
+     */
+    checked?: boolean;
+    /**
+     * The `RadioTile` content.
+     */
+    children?: React.ReactNode;
+    /**
+     * Provide an optional `className` to be applied to the underlying `<label>`.
+     */
+    className?: string;
+    /**
+     * Specify whether the `RadioTile` should be disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Provide a unique id for the underlying `<input>`.
+     */
+    id?: string;
+    /**
+     * `true` to use the light version. For use on `$layer-01` backgrounds only.
+     * Don't use this to make tile background color the same as the container background color.
+     *
+     * @deprecated This prop is no longer needed and has been deprecated in v11 in favor of the new Layer component. It will be removed in the next major release.
+     */
+    light?: boolean;
+    /**
+     * Provide a `name` for the underlying `<input>`.
+     */
+    name?: string;
+    /**
+     * Provide an optional `onChange` hook that is called each time the value of
+     * the underlying `<input>` changes.
+     */
+    onChange?: (value: string | number, name: string | undefined, event: React.ChangeEvent<HTMLInputElement> | React.KeyboardEvent<HTMLInputElement>) => void;
+    /**
+     * Specify the tab index of the underlying `<input>`.
+     */
+    tabIndex?: number;
+    /**
+     * Specify the value of the underlying `<input>`.
+     */
+    value: string | number;
+}
+declare const RadioTile: React.ForwardRefExoticComponent<RadioTileProps & React.RefAttributes<HTMLInputElement>>;
+export default RadioTile;