@itwin/itwinui-react 3.11.3 → 3.12.1

package/esm/core/LabeledSelect/LabeledSelect.js

@@ -1,50 +1,65 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
 import { Select } from '../Select/Select.js';
 import { StatusMessage } from '../StatusMessage/StatusMessage.js';
 import { InputGrid } from '../InputGrid/InputGrid.js';
 import { Label } from '../Label/Label.js';
-import { Icon } from '../Icon/Icon.js';
-/**
- * Labeled select component to select value from options.
- * @example
- * <LabeledSelect
- *   label='Select Label'
- *   options={[
- *     { value: 1, label: 'Item #1' },
- *     { value: 2, label: 'Item #2' },
- *     { value: 3, label: 'Item #3' },
- *   ]}
- *   message='Help Message'
- * />
- * <LabeledSelect
- *   label='Select Label'
- *   options={[
- *     { value: 1, label: 'Item #1' },
- *     { value: 2, label: 'Item #2' },
- *     { value: 3, label: 'Item #3' },
- *   ]}
- *   message='Positive Message'
- *   status='positive'
- * />
- * <LabeledSelect
- *   label='Select Label'
- *   options={[
- *     { value: 1, label: 'Item #1' },
- *     { value: 2, label: 'Item #2' },
- *     { value: 3, label: 'Item #3' },
- *   ]}
- *   message='Custom Message'
- *   svgIcon={<SvgCamera />}
- * />
- */
 export const LabeledSelect = React.forwardRef((props, forwardedRef) => {
-    const { className, disabled = false, label, message, status, svgIcon, displayStyle = 'default', style, required = false, wrapperProps, labelProps, messageContentProps, messageIconProps, ...rest } = props;
-    return (React.createElement(InputGrid, { labelPlacement: displayStyle, "data-iui-status": status, ...wrapperProps },
-        label && (React.createElement(Label, { as: 'div', required: required, disabled: disabled, ...labelProps }, label)),
-        React.createElement(Select, { disabled: disabled, className: className, style: style, required: props.native ? required : undefined, ...rest, ref: forwardedRef, ...{ styleType: 'default' } }),
-        typeof message === 'string' ? (React.createElement(StatusMessage, { status: status, startIcon: svgIcon, iconProps: messageIconProps, contentProps: messageContentProps }, message)) : (message)));
+  const {
+    className,
+    disabled = false,
+    label,
+    message,
+    status,
+    svgIcon,
+    displayStyle = 'default',
+    style,
+    required = false,
+    wrapperProps,
+    labelProps,
+    messageContentProps,
+    messageIconProps,
+    ...rest
+  } = props;
+  return React.createElement(
+    InputGrid,
+    {
+      labelPlacement: displayStyle,
+      'data-iui-status': status,
+      ...wrapperProps,
+    },
+    label &&
+      React.createElement(
+        Label,
+        {
+          as: 'div',
+          required: required,
+          disabled: disabled,
+          ...labelProps,
+        },
+        label,
+      ),
+    React.createElement(Select, {
+      disabled: disabled,
+      className: className,
+      style: style,
+      required: props.native ? required : undefined,
+      ...rest,
+      ref: forwardedRef,
+      ...{
+        styleType: 'default',
+      },
+    }),
+    typeof message === 'string'
+      ? React.createElement(
+          StatusMessage,
+          {
+            status: status,
+            startIcon: svgIcon,
+            iconProps: messageIconProps,
+            contentProps: messageContentProps,
+          },
+          message,
+        )
+      : message,
+  );
 });

package/esm/core/LabeledSelect/LabeledSelect.types-test.js

@@ -0,0 +1,102 @@
+import { useRef } from 'react';
+import { LabeledSelect } from './LabeledSelect.js';
+() => {
+  const ref = useRef(null);
+  return React.createElement(
+    React.Fragment,
+    null,
+    React.createElement(LabeledSelect, {
+      options: [
+        {
+          value: 1,
+          label: 'Option 1',
+        },
+        {
+          value: 2,
+          label: 'Option 2',
+        },
+        {
+          value: 3,
+          label: 'Option 3',
+        },
+      ],
+      onChange: (value) => {
+        const returnValue = value;
+        return returnValue;
+      },
+      ref: ref,
+    }),
+  );
+};
+() => {
+  return React.createElement(
+    React.Fragment,
+    null,
+    React.createElement(LabeledSelect, {
+      options: [
+        {
+          value: 1,
+          label: 'Option 1',
+        },
+        {
+          value: 2,
+          label: 'Option 2',
+        },
+        {
+          value: 3,
+          label: 'Option 3',
+        },
+      ],
+      onChange: (value) => {
+        const returnValue = value;
+        return returnValue;
+      },
+    }),
+  );
+};
+() => {
+  return React.createElement(
+    React.Fragment,
+    null,
+    React.createElement(LabeledSelect, {
+      label: 'Select Label',
+      options: [
+        {
+          value: '1',
+          label: 'Item #1',
+        },
+        {
+          value: '2',
+          label: 'Item #2',
+        },
+        {
+          value: '3',
+          label: 'Item #3',
+        },
+      ],
+      onChange: (value) => {
+        const returnValue = value;
+        return returnValue;
+      },
+    }),
+  );
+};
+() => {
+  return React.createElement(
+    React.Fragment,
+    null,
+    React.createElement(LabeledSelect, {
+      label: 'Select Label',
+      options: [
+        {
+          value: 1,
+          label: 'Item #1',
+        },
+      ],
+      onChange: (value) => {
+        const returnValue = value;
+        return returnValue;
+      },
+    }),
+  );
+};

package/esm/core/LabeledTextarea/LabeledTextarea.js

@@ -1,36 +1,10 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
-import { Icon } from '../Icon/Icon.js';
-import { InputGrid } from '../InputGrid/InputGrid.js';
 import { LabeledInput } from '../LabeledInput/LabeledInput.js';
-/**
- * Textarea wrapper that allows for additional styling and labelling
- * @example
- * <LabeledTextarea
- *  label='Textarea Label'
- *  message='Help Message'
- *  placeholder='This is a textarea'
- * />
- * <LabeledTextarea
- *  label='Disabled Textarea Label'
- *  message='Help Message'
- *  placeholder='This is a textarea'
- *  disabled={true}
- * />
- * <LabeledTextarea
- *  label='Textarea Label'
- *  message='Negative Message'
- *  placeholder='This is a textarea'
- *  status='negative'
- * />
- */
 export const LabeledTextarea = React.forwardRef((props, forwardedRef) => {
-    return (
-    // ref types don't match but it's internal, so ts-ignore is ok here
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    React.createElement(LabeledInput, { as: 'textarea', rows: 3, ref: forwardedRef, ...props }));
+  return React.createElement(LabeledInput, {
+    as: 'textarea',
+    rows: 3,
+    ref: forwardedRef,
+    ...props,
+  });
 });

package/esm/core/LinkAction/LinkAction.d.ts

@@ -9,7 +9,7 @@ import type { PolymorphicForwardRefComponent } from '../../utils/props.js';
  *   </Surface>
  * </LinkBox>
  */
-export declare const LinkAction: PolymorphicForwardRefComponent<"a", {}>;
+export declare const LinkAction: PolymorphicForwardRefComponent<"a">;
 /**
  * Polymorphic link box component.
  * Used to wrap around your component to use LinkAction.

package/esm/core/LinkAction/LinkAction.js

@@ -1,36 +1,16 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
 import cx from 'classnames';
 import { polymorphic } from '../../utils/functions/polymorphic.js';
 import { Box } from '../../utils/components/index.js';
-/**
- * Polymorphic link action component.
- * It is rendered as `a` by default.
- * @example
- * <LinkBox>
- *   <Surface>
- *     <LinkAction href='/new-page'>Whole card is clickable</LinkAction>
- *   </Surface>
- * </LinkBox>
- */
 export const LinkAction = React.forwardRef((props, forwardedRef) => {
-    const { as: asProp = (!!props.href ? 'a' : 'button') } = props;
-    return (React.createElement(Box, { ...props, as: asProp, className: cx('iui-link-action', props.className), ref: forwardedRef }));
+  const { as: asProp = !!props.href ? 'a' : 'button' } = props;
+  return React.createElement(Box, {
+    ...props,
+    as: asProp,
+    className: cx('iui-link-action', props.className),
+    ref: forwardedRef,
+  });
 });
 LinkAction.displayName = 'LinkAction';
-/**
- * Polymorphic link box component.
- * Used to wrap around your component to use LinkAction.
- * Rendered as `div` by default
- * @example
- * <LinkBox>
- *   <Surface>
- *     <LinkAction href='/new-page'>Whole card is clickable</LinkAction>
- *   </Surface>
- * </LinkBox>
- */
 export const LinkBox = polymorphic.div('iui-link-box');
 LinkBox.displayName = 'LinkBox';

package/esm/core/List/List.js

@@ -1,7 +1,5 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
 import { polymorphic } from '../../utils/index.js';
-export const List = polymorphic.ul('iui-list', { role: 'list' });
+export const List = polymorphic.ul('iui-list', {
+  role: 'list',
+});
 List.displayName = 'List';

package/esm/core/List/ListItem.d.ts

@@ -44,7 +44,7 @@ export declare const ListItem: PolymorphicForwardRefComponent<"li", ListItemOwnP
     /**
      * Icon to be placed at the beginning or end of the ListItem.
      */
-    Icon: PolymorphicForwardRefComponent<NonNullable<keyof JSX.IntrinsicElements>, {}>;
+    Icon: PolymorphicForwardRefComponent<keyof JSX.IntrinsicElements, {}>;
     /**
      * Wrapper for the main content of the ListItem.
      *
@@ -53,7 +53,7 @@ export declare const ListItem: PolymorphicForwardRefComponent<"li", ListItemOwnP
      *   and push the icon to the end
      * - When using `ListItem.Description`.
      */
-    Content: PolymorphicForwardRefComponent<NonNullable<keyof JSX.IntrinsicElements>, {}>;
+    Content: PolymorphicForwardRefComponent<keyof JSX.IntrinsicElements, {}>;
     /**
      * Description to be used in addition to the main label of the ListItem.
      * Should be used as a child of `ListItem.Content`.
@@ -66,7 +66,7 @@ export declare const ListItem: PolymorphicForwardRefComponent<"li", ListItemOwnP
      *  </ListItem.Content>
      * </ListItem>
      */
-    Description: PolymorphicForwardRefComponent<NonNullable<keyof JSX.IntrinsicElements>, {}>;
+    Description: PolymorphicForwardRefComponent<keyof JSX.IntrinsicElements, {}>;
     /**
      * Wrapper over [LinkAction](https://itwinui.bentley.com/docs/linkaction) which allows rendering a link inside a ListItem.
      * This ensures that clicking anywhere on the ListItem will trigger the link.

package/esm/core/List/ListItem.js

@@ -1,78 +1,41 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
 import cx from 'classnames';
 import { polymorphic, Box } from '../../utils/index.js';
 import { LinkAction } from '../LinkAction/LinkAction.js';
 const ListItemComponent = React.forwardRef((props, ref) => {
-    const { size = 'default', disabled = false, active = false, actionable = false, focused = false, className, ...rest } = props;
-    return (React.createElement(Box, { as: 'li', className: cx('iui-list-item', className), "data-iui-active": active ? 'true' : undefined, "data-iui-disabled": disabled ? 'true' : undefined, "data-iui-size": size === 'large' ? 'large' : undefined, "data-iui-actionable": actionable ? 'true' : undefined, "data-iui-focused": focused ? 'true' : undefined, ref: ref, ...rest }));
+  const {
+    size = 'default',
+    disabled = false,
+    active = false,
+    actionable = false,
+    focused = false,
+    className,
+    ...rest
+  } = props;
+  return React.createElement(Box, {
+    as: 'li',
+    className: cx('iui-list-item', className),
+    'data-iui-active': active ? 'true' : undefined,
+    'data-iui-disabled': disabled ? 'true' : undefined,
+    'data-iui-size': size === 'large' ? 'large' : undefined,
+    'data-iui-actionable': actionable ? 'true' : undefined,
+    'data-iui-focused': focused ? 'true' : undefined,
+    ref: ref,
+    ...rest,
+  });
 });
 ListItemComponent.displayName = 'ListItem';
-// ----------------------------------------------------------------------------
 const ListItemIcon = polymorphic('iui-list-item-icon');
 ListItemIcon.displayName = 'ListItem.Icon';
-// ----------------------------------------------------------------------------
 const ListItemContent = polymorphic('iui-list-item-content');
 ListItemContent.displayName = 'ListItem.Content';
-// ----------------------------------------------------------------------------
 const ListItemDescription = polymorphic('iui-list-item-description');
 ListItemDescription.displayName = 'ListItem.Description';
-// ----------------------------------------------------------------------------
 const ListItemAction = LinkAction;
 ListItemAction.displayName = 'ListItem.Action';
-// ----------------------------------------------------------------------------
-// Exported compound component
-/**
- * A generic ListItem component that can be used simply for displaying data, or as a base
- * for the list items in a more complex component (e.g. a custom Select).
- *
- * Includes support for left/right icons, multiple lines of text, and hover/focus/active/disabled styling.
- *
- * @example
- * <List>
- *   <ListItem>item 1</ListItem>
- *   <ListItem>item 2</ListItem>
- *   <ListItem>item 3</ListItem>
- * </List>
- */
 export const ListItem = Object.assign(ListItemComponent, {
-    /**
-     * Icon to be placed at the beginning or end of the ListItem.
-     */
-    Icon: ListItemIcon,
-    /**
-     * Wrapper for the main content of the ListItem.
-     *
-     * For basic list items, this wrapper is not needed, but it can be useful for two cases:
-     * - When using an end icon. The `ListItem.Content` will fill the available space
-     *   and push the icon to the end
-     * - When using `ListItem.Description`.
-     */
-    Content: ListItemContent,
-    /**
-     * Description to be used in addition to the main label of the ListItem.
-     * Should be used as a child of `ListItem.Content`.
-     *
-     * @example
-     * <ListItem>
-     *  <ListItem.Content>
-     *   <div>some list item</div>
-     *   <ListItem.Description>description for this item</ListItem.Description>
-     *  </ListItem.Content>
-     * </ListItem>
-     */
-    Description: ListItemDescription,
-    /**
-     * Wrapper over [LinkAction](https://itwinui.bentley.com/docs/linkaction) which allows rendering a link inside a ListItem.
-     * This ensures that clicking anywhere on the ListItem will trigger the link.
-     *
-     * @example
-     * <ListItem>
-     *  <ListItem.Action href='https://example.com'>Example link</ListItem.Action>
-     * </ListItem>
-     */
-    Action: ListItemAction,
+  Icon: ListItemIcon,
+  Content: ListItemContent,
+  Description: ListItemDescription,
+  Action: ListItemAction,
 });

package/esm/core/Menu/Menu.d.ts

@@ -1,5 +1,8 @@
 import * as React from 'react';
-import type { PolymorphicForwardRefComponent } from '../../utils/index.js';
+import type { PolymorphicForwardRefComponent, PortalProps } from '../../utils/index.js';
+import { usePopover } from '../Popover/Popover.js';
+import { useInteractions, type UseListNavigationProps } from '@floating-ui/react';
+type UsePopoverProps = Parameters<typeof usePopover>[0];
 type MenuProps = {
     /**
      * Menu items. Recommended to use `MenuItem` components.
@@ -9,13 +12,84 @@ type MenuProps = {
      */
     children: React.ReactNode;
     /**
-     * If true, the first selected or enabled menu item will be focused automatically.
-     * @default true
+     * The trigger that opens the menu.
      */
-    setFocus?: boolean;
-};
+    trigger: React.ReactNode;
+    /**
+     * You can use this optional prop when the position reference is not the trigger.
+     * (Equivalent to using FloatingUI's `floating.refs.setPositionReference`)
+     */
+    positionReference?: Parameters<ReturnType<typeof usePopover>['refs']['setPositionReference']>[0];
+    /**
+     * Use this prop to override the default props passed to `usePopover` and `useListNavigation`.
+     */
+    popoverProps?: Omit<UsePopoverProps, 'interactions'> & {
+        interactions?: UsePopoverProps['interactions'] & {
+            listNavigation?: Partial<UseListNavigationProps>;
+        };
+    };
+} & Pick<PortalProps, 'portal'>;
 /**
- * Basic menu component. Can be used for select or dropdown components.
+ * @private
+ *
+ * Used for dropdown components. E.g. `DropdownMenu`, `SplitButton`.
+ *
+ * What needs to be handled **manually**:
+ * - Menu items need to spread `MenuContext.popover.getItemProps()`.
+ * - Menu items need to focus itself on hover.
+ *
+ * What is handled automatically:
+ * - the portaling: use the optional `portal` prop for more customization
+ * - conditional rendering based on the popover's open state
+ * - spreading the popover props `getFloatingProps` and `getReferenceProps`.
+ *   - As mentioned above, `getItemProps` need to be spread **manually** in the menu item.
+ * - setting the refs: use the optional`positionReference` prop to set the position reference
+ * - keyboard navigation: use the `interactions.listNavigation` prop for more customization
+ * - registering a `FloatingNode` in the `FloatingTree` if an ancestral `FloatingTree` is found
+ * - focus management:
+ *   - focuses items on hover.
+ *   - if *not* in a `FloatingTree`, focus moves to the trigger when the menu is closed.
+ *     If in a `FloatingTree`, focus does not move back to the trigger since menu items handle the focus.
+ * - setting `aria-expanded` accordingly depending on the menu open state
+ *
+ * All `Menu` popover interactions are identical to `usePopover`'s interactions. Exception:
+ * - `hover`: When the `Menu` is within a `FloatingTree`, if a submenu has focus, the hover interaction is automatically
+ * disabled. This helps to keep the last hovered/focused submenu open even upon hovering out.
+ *
+ * @example
+ * const trigger = <Button>Menu</Button>;
+ * const [positionReference, setPositionReference] = React.useState<HTMLDivElement | null>(null);
+ * const popoverProps = { matchWidth: true };
+ * const nodeId = useFloatingNodeId();
+ *
+ * return (
+ *   <Box ref={setPositionReference}>
+ *     <Menu
+ *       trigger={trigger}
+ *       positionReference={positionReference}
+ *       nodeId={nodeId}
+ *       popoverProps={popoverProps}
+ *     >
+ *       <MenuItem>Item 1</MenuItem>
+ *       <MenuItem>Item 2</MenuItem>
+ *     </Menu>
+ *   </Box>
+ * );
  */
 export declare const Menu: PolymorphicForwardRefComponent<"div", MenuProps>;
+export type TreeEvent = {
+    nodeId: string;
+    parentId: string | null;
+};
+type PopoverGetItemProps = ({ focusableItemIndex, userProps, }: {
+    /**
+     * Index of this item out of all the focusable items in the parent `Menu`
+     */
+    focusableItemIndex: number | undefined;
+    userProps?: Parameters<NonNullable<ReturnType<typeof useInteractions>['getItemProps']>>[0];
+}) => ReturnType<ReturnType<typeof useInteractions>['getItemProps']>;
+export declare const MenuContext: React.Context<{
+    popoverGetItemProps: PopoverGetItemProps;
+    focusableElements: HTMLElement[];
+} | undefined>;
 export {};