@iress-oss/ids-components 6.0.0-alpha.3 → 6.0.0-alpha.30

package/dist/components/Popover/hooks/useFloatingPopover.d.ts

@@ -0,0 +1,192 @@
+import { RefObject } from 'react';
+import { ControlledStateProps } from '../../../hooks/useControlledState';
+import { OffsetOptions, OpenChangeReason, UseFloatingReturn, useInteractions } from '@floating-ui/react';
+import { FloatingUIAligns } from '../../../types';
+import { PopoverVirtualNode } from './usePopoverItem';
+import { PopoverAriaHookReturn } from './usePopoverAria';
+export interface FloatingPopoverHookProps {
+    /**
+     * The alignment of the popover relative to the activator element. It determines the placement of the popover and how it will flip when there is not enough space in the viewport.
+     * @default auto
+     */
+    align?: FloatingUIAligns;
+    /**
+     * Whether the first item in the popover should be automatically highlighted (ie. focused or virtually focused) when the popover is opened.
+     * @default true
+     */
+    autoHighlight?: boolean;
+    /**
+     * The component name used in the useControlledState hook to manage the controlled state of the popover. It is used to determine whether the popover is controlled by the parent component or not.
+     * @default IressPopover
+     */
+    component?: ControlledStateProps['component'];
+    /**
+     * Whether the popover is triggered by an input element, which requires different middleware to prevent the popover from closing when interacting with the input.
+     */
+    defaultShow?: boolean;
+    /**
+     * The index of the item that should be focused or virtually focused when the popover is opened. It is used by the usePopoverNavigation hook to set the initial active index of the popover items.
+     * @default 0
+     */
+    focusStartIndex?: number;
+    /**
+     * Whether the popover is triggered by an input element, which requires different middleware to prevent the popover from closing when interacting with the input.
+     */
+    hasInputActivator?: boolean;
+    /**
+     * Whether the popover should match the width of the activator element. It is used to determine whether to apply the size middleware to the popover or not.
+     * @default false
+     */
+    matchActivatorWidth?: boolean;
+    /**
+     * The offset of the popover relative to the activator element. It is used to determine the distance between the popover and the activator element, and can be used to fine-tune the position of the popover.
+     * @default 5
+     */
+    offset?: OffsetOptions;
+    /**
+     * This function is called when the popover is opened, either by click or keyboard interaction. It is used to trigger any side effects that should happen when the popover is opened, such as setting the active index of the popover items or managing focus.
+     * @param e - The event that triggered the popover to open, either a click event or a keyboard event.
+     * @param reason - The reason why the popover was opened, either 'click', 'keyboard', or 'focus'.
+     * @param activeIndex - The index of the currently active item in the popover, which is either focused or virtually focused. It can be used to determine which item is active when the popover is opened.
+     */
+    onActivated?: (e?: Event, reason?: OpenChangeReason, activeIndex?: number | null) => void;
+    /**
+     * This function is called when the popover is closed, either by click, keyboard interaction, or clicking outside the popover. It is used to trigger any side effects that should happen when the popover is closed, such as resetting the active index of the popover items or managing focus.
+     * @param e - The event that triggered the popover to close, either a click event, a keyboard event, or a dismiss event.
+     * @param reason - The reason why the popover was closed, either 'click', 'keyboard', 'dismiss', or 'focus'.
+     * @param activeIndex - The index of the currently active item in the popover, which is either focused or virtually focused. It can be used to determine which item was active when the popover was closed.
+     */
+    onDeactivated?: (e?: Event, reason?: OpenChangeReason, activeIndex?: number | null) => void;
+    /**
+     * This function is called when the active index of the popover items is changed by keyboard navigation. It is used to trigger any side effects that should happen when navigating through the popover items, such as updating the virtual focus or managing aria attributes.
+     * @param activeIndex - The index of the currently active item in the popover, which is either focused or virtually focused. It can be used to determine which item is active when navigating through the popover items.
+     */
+    onNavigate?: (activeIndex: number | null) => void;
+    /**
+     * When set to `true` the popover will be visible. Use for controlled popovers. If not provided, the popover will manage its own state internally.
+     */
+    show?: boolean;
+    /**
+     * Describes the type of content contained in the popover, which is used to determine the role of the popover and how it should be navigated by screen readers and assistive technologies.
+     * It is used by components such as `IressMenu` to manage the aria attributes and keyboard navigation of the items in the popover.
+     */
+    type?: 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
+    /**
+     * Whether the popover should use virtual focus to manage the focus state of the items in the popover. When true, the popover will keep the focus on the reference element and use aria-activedescendant to indicate which item is active, allowing for more flexible keyboard navigation patterns.
+     */
+    virtualFocus?: boolean;
+    /**
+     * Whether this popover is nested inside another popover (e.g. a subdraw menu).
+     * When true, the activator opens with ArrowRight instead of ArrowDown,
+     * and ArrowLeft closes the submenu from within.
+     */
+    nested?: boolean;
+}
+export interface FloatingPopoverHookReturn extends PopoverAriaHookReturn {
+    /**
+     * The index of the currently active item in the popover (ie. which item is currently focused or virtually focused).
+     */
+    activeIndex: number | null;
+    /**
+     * The API returned by the useFloating hook.
+     */
+    api: UseFloatingReturn;
+    /**
+     * A function that returns the truly focusable activator element.
+     * It is normally used to set the focus on the activator when the popover is closed and ensure a relationship between the activator and the popover.
+     */
+    getFocusableActivator: () => HTMLElement | undefined;
+    /**
+     * A function that returns the virtually focused item in the popover.
+     * It is normally used to trigger onClick and onKeyDown events on the item as if it was focused.
+     */
+    getVirtualFocus?: () => PopoverVirtualNode | null;
+    /**
+     * A function that checks whether there is a nested element assuming the role of the popover.
+     * It is used by `IressMenu` to force the popover to a certain role so that the screen reader can navigate it correctly.
+     */
+    hasInnerRole: () => boolean;
+    /**
+     * The interactions returned by the useInteractions hook.
+     * It is used to manage the interactions of the popover activator and content, such as click and dismiss.
+     */
+    interactions: ReturnType<typeof useInteractions>;
+    /**
+     * This function checks whether an element is the same as the activator element.
+     * It is used by components such as `IressButton` to style the activator when the popover is open.
+     */
+    isActiveActivator: (element: HTMLElement | null) => boolean;
+    /**
+     * If controlled, this will return true, meaning the popover is controlled by the parent component and will not change its state on its own.
+     * It is used by components such as `IressSelect` to manage the state of the popover using other methods.
+     */
+    isControlled: boolean;
+    /**
+     * If virtually focused, this will return true, meaning the popover is using virtual focus to manage the focus state of the items in the popover.
+     * It is used by components such as `useMenuItem` to check whether it should set the tab index of an item or not.
+     */
+    isVirtualFocus: boolean;
+    /**
+     * The list of items in the popover.
+     * It is used by other components to manage the aria attributes and keyboard navigation of the items.
+     */
+    list: RefObject<(HTMLElement | null)[]>;
+    /**
+     * Whether this popover is nested inside another popover (e.g. a subdraw menu).
+     * When true, the activator uses ArrowRight to open and ArrowLeft closes from within.
+     */
+    nested: boolean;
+    /**
+     * Resets the active index of the popover items, either to the `focusStartIndex` or null
+     */
+    resetActiveIndex: () => void;
+    /**
+     * Set the current active index of the popover items.
+     */
+    setActiveIndex: (newActiveIndex: number | null) => void;
+    /**
+     * This function is used to set the state of the popover without triggering the Floating UI handlers such as focus handling as well as onActivated and onDeactivated.
+     * It is used by `useMenuItem` to close the popover when an item is selected.
+     *
+     * For most cases, you should use the `setShowWithReason` function instead.
+     */
+    setShow: (flag?: boolean) => void;
+    /**
+     * This function is used to set the state of the popover and trigger the Floating UI handlers such as focus handling.
+     * Depending on the reason, it will change the way focus is handled.
+     */
+    setShowWithReason: (flag: boolean, e?: Event, reason?: OpenChangeReason) => void;
+    /**
+     * This function is used to set the state of the popover to have an inner role.
+     * It is used by components such as `IressMenu` to force the popover to a certain role so that the screen reader can navigate it correctly.
+     */
+    setHasInnerRole: (flag: boolean) => void;
+    /**
+     * This function is used to set the virtual focus of the popover.
+     * It is used by components such as `IressSelect` with searchable options to manage the focus state of the items in the popover.
+     */
+    setVirtualFocus?: (node: PopoverVirtualNode | null) => void;
+    /**
+     * The state of the popover, whether it is open or closed.
+     */
+    show: boolean;
+    /**
+     * The type of the popover, which is used to determine the role of the popover.
+     * It is used by components such as `IressMenu` to manage the aria attributes and keyboard navigation of the items.
+     */
+    type?: FloatingPopoverHookProps['type'];
+}
+/**
+ * This is a wrapper around the useFloating hook from Floating UI specifically for popover components.
+ * - It manages the state of the popover, including whether it is open or closed, and provides a controlled state for the popover.
+ * - It also manages the middleware for the popover, including the size middleware to match the activator width.
+ * - It uses the usePopoverNavigation hook to manage the keyboard navigation of popover items.
+ * - It provides a way to set the active index of the popover items, and to manage the focus state of the popover items.
+ * - It provides a way to set the virtual focus of the popover items, and to manage the focus state of the popover items.
+ * - It provides a way to set the hasInnerRole state, which is used to determine whether the popover has an inner role or not.
+ */
+export declare const useFloatingPopover: ({ align, autoHighlight, component, defaultShow, focusStartIndex, hasInputActivator, matchActivatorWidth, nested, offset: offsetValue, onActivated, onDeactivated, onNavigate, show: showProp, type, virtualFocus, }: FloatingPopoverHookProps) => FloatingPopoverHookReturn;
+/**
+ * This context is used to provide the popover state and API to allow items to be navigatable by keyboard and screen readers.
+ */
+export declare const FloatingPopoverContext: import('react').Context<FloatingPopoverHookReturn | undefined>;

package/dist/components/Popover/hooks/useFloatingPopover.js

@@ -0,0 +1,145 @@
+import { createContext as K, useRef as I, useMemo as x, useCallback as v } from "react";
+import { useControlledState as T } from "../../../hooks/useControlledState.js";
+import { m as W, u as X, n as B, b as J, c as L, d as Q, o as F, j as M, i as Y, s as Z, p as ee } from "../../../floating-ui.react-B0nDXRN6.js";
+import { usePopoverNavigation as oe } from "./usePopoverNavigation.js";
+import { focusableElements as te } from "../../../helpers/dom/focusableElements.js";
+import { usePopoverAria as se } from "./usePopoverAria.js";
+import { closestCrossShadow as ne } from "../../../helpers/dom/closestCrossShadow.js";
+import { GlobalCSSClass as re } from "../../../enums.js";
+const ie = 200, xe = ({
+  align: i = "auto",
+  autoHighlight: N = !0,
+  component: V = "IressPopover",
+  defaultShow: k,
+  focusStartIndex: d,
+  hasInputActivator: a,
+  matchActivatorWidth: w,
+  nested: C,
+  offset: p = 5,
+  onActivated: H,
+  onDeactivated: _,
+  onNavigate: $,
+  show: j,
+  type: l,
+  virtualFocus: n
+}) => {
+  const h = I(!1), b = I(null), {
+    isControlled: g,
+    setValue: f,
+    value: r
+  } = T({
+    component: V,
+    defaultValue: k,
+    propName: "show",
+    value: j
+  }), q = x(() => {
+    const e = a ? [F(p), M({ padding: 5 })] : [
+      F(p),
+      i === "auto" ? Y() : M(),
+      Z((t) => ({
+        mainAxis: !ne(
+          t.elements.reference,
+          `.${re.Slideout}`
+        )
+      }))
+    ];
+    return w ? [
+      ...e,
+      W({
+        apply({ rects: t, availableHeight: s, elements: D }) {
+          requestAnimationFrame(() => {
+            Object.assign(D.floating.style, {
+              minWidth: `${t.reference.width}px`,
+              maxHeight: s > ie ? `${s}px` : void 0
+            });
+          });
+        },
+        padding: 5
+      })
+    ] : e;
+  }, [a, p, i, w]), o = X({
+    open: r,
+    onOpenChange: (e, t, s) => {
+      f(e), e ? H?.(t, s, c) : _?.(t, s, c);
+    },
+    middleware: q,
+    placement: i === "auto" ? void 0 : i,
+    whileElementsMounted: ee
+  }), { activeIndex: c, list: S, listNav: G, setActiveIndex: u } = oe(
+    o.context,
+    l,
+    {
+      focusItemOnOpen: N,
+      virtual: n
+    },
+    $,
+    d
+  ), U = B(o.context, {
+    enabled: !a
+  }), y = J(o.context, {
+    enabled: !0,
+    escapeKey: !a
+  }), z = L(o.context, {
+    role: l
+  }), P = se(), O = Q([U, y, z, G]), R = x(() => n ? {
+    getVirtualFocus: () => b.current,
+    setVirtualFocus: (e) => {
+      b.current = e;
+    }
+  } : {}, [n]), m = v(() => {
+    const e = o.elements.reference;
+    return e?.querySelector("[role=combobox]") ?? te(e)[0];
+  }, [o.elements.reference]), A = v(
+    (e) => !e || !r ? !1 : e === m(),
+    [m, r]
+  ), E = v(() => {
+    u(d ?? null);
+  }, [d, u]);
+  return x(
+    () => ({
+      activeIndex: c,
+      ...P,
+      api: o,
+      getFocusableActivator: m,
+      hasInnerRole: () => h.current,
+      interactions: O,
+      isActiveActivator: A,
+      isControlled: g,
+      isVirtualFocus: !!n,
+      list: S,
+      nested: !!C,
+      resetActiveIndex: E,
+      setActiveIndex: u,
+      setShow: f,
+      setShowWithReason: o.context.onOpenChange,
+      setHasInnerRole: (e) => {
+        h.current = e;
+      },
+      show: !!r,
+      type: l,
+      ...R
+    }),
+    [
+      c,
+      o,
+      P,
+      m,
+      O,
+      A,
+      g,
+      S,
+      C,
+      E,
+      u,
+      f,
+      r,
+      l,
+      R,
+      n
+    ]
+  );
+}, ve = K(void 0);
+export {
+  ve as FloatingPopoverContext,
+  xe as useFloatingPopover
+};

package/dist/components/Popover/hooks/usePopover.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Allows you to access the popover context from within a child component.
+ * @returns The popover context.
+ */
+export declare const usePopover: () => import('./useFloatingPopover').FloatingPopoverHookReturn | undefined;

package/dist/components/Popover/hooks/usePopover.js

@@ -1,143 +1,6 @@
-import { createContext as z, useRef as V, useMemo as p, useCallback as x } from "react";
-import { useControlledState as D } from "../../../hooks/useControlledState.js";
-import { o as A, j as E, i as K, s as T, m as W, u as X, n as B, b as J, c as L, d as Q, p as Y } from "../../../floating-ui.react-BetVZ099.js";
-import { usePopoverNavigation as Z } from "./usePopoverNavigation.js";
-import { focusableElements as ee } from "../../../helpers/dom/focusableElements.js";
-import { usePopoverAria as oe } from "./usePopoverAria.js";
-import { closestCrossShadow as te } from "../../../helpers/dom/closestCrossShadow.js";
-import { GlobalCSSClass as se } from "../../../enums.js";
-const ne = 200, fe = ({
-  align: i = "auto",
-  autoHighlight: I = !0,
-  component: M = "IressPopover",
-  defaultShow: N,
-  focusStartIndex: d,
-  hasInputActivator: a,
-  matchActivatorWidth: v,
-  onActivated: k,
-  onDeactivated: H,
-  onNavigate: _,
-  show: $,
-  type: l,
-  virtualFocus: n
-}) => {
-  const w = V(!1), C = V(null), {
-    isControlled: h,
-    setValue: f,
-    value: r
-  } = D({
-    component: M,
-    defaultValue: N,
-    propName: "show",
-    value: $
-  }), j = p(() => {
-    const e = a ? [A(5), E({ padding: 5 })] : [
-      A(5),
-      i === "auto" ? K() : E(),
-      T((t) => ({
-        mainAxis: !te(
-          t.elements.reference,
-          `.${se.Slideout}`
-        )
-      }))
-    ];
-    return v ? [
-      ...e,
-      W({
-        apply({ rects: t, availableHeight: s, elements: y }) {
-          requestAnimationFrame(() => {
-            Object.assign(y.floating.style, {
-              minWidth: `${t.reference.width}px`,
-              maxHeight: s > ne ? `${s}px` : void 0
-            });
-          });
-        },
-        padding: 5
-      })
-    ] : e;
-  }, [v, a, i]), o = X({
-    open: r,
-    onOpenChange: (e, t, s) => {
-      f(e), e ? k?.(t, s, c) : H?.(t, s, c);
-    },
-    middleware: j,
-    placement: i === "auto" ? void 0 : i,
-    whileElementsMounted: Y
-  }), { activeIndex: c, list: b, listNav: q, setActiveIndex: u } = Z(
-    o.context,
-    l,
-    {
-      focusItemOnOpen: I,
-      virtual: n
-    },
-    _,
-    d
-  ), F = B(o.context, {
-    enabled: !a
-  }), G = J(o.context, {
-    enabled: !0,
-    escapeKey: !a
-  }), U = L(o.context, {
-    role: l
-  }), S = oe(), P = Q([F, G, U, q]), g = p(() => n ? {
-    getVirtualFocus: () => C.current,
-    setVirtualFocus: (e) => {
-      C.current = e;
-    }
-  } : {}, [n]), m = x(() => {
-    const e = o.elements.reference;
-    return e?.querySelector("[role=combobox]") ?? ee(e)[0];
-  }, [o.elements.reference]), O = x(
-    (e) => !e || !r ? !1 : e === m(),
-    [m, r]
-  ), R = x(() => {
-    u(d ?? null);
-  }, [d, u]);
-  return p(
-    () => ({
-      activeIndex: c,
-      ...S,
-      api: o,
-      getFocusableActivator: m,
-      hasInnerRole: () => w.current,
-      interactions: P,
-      isActiveActivator: O,
-      isControlled: h,
-      isVirtualFocus: !!n,
-      list: b,
-      resetActiveIndex: R,
-      setActiveIndex: u,
-      setShow: f,
-      setShowWithReason: o.context.onOpenChange,
-      setHasInnerRole: (e) => {
-        w.current = e;
-      },
-      show: !!r,
-      type: l,
-      ...g
-    }),
-    [
-      c,
-      o,
-      S,
-      m,
-      P,
-      O,
-      h,
-      b,
-      R,
-      u,
-      f,
-      r,
-      l,
-      g,
-      n
-    ]
-  );
-}, pe = z(
-  void 0
-);
+import { useContext as o } from "react";
+import { FloatingPopoverContext as t } from "./useFloatingPopover.js";
+const p = () => o(t);
 export {
-  pe as PopoverContext,
-  fe as usePopover
+  p as usePopover
 };

package/dist/components/Popover/hooks/usePopoverActivatorInteractions.d.ts

@@ -0,0 +1,15 @@
+import { KeyboardEvent, FocusEvent } from 'react';
+import { IressUnstyledProps } from '../../../types';
+import { FloatingPopoverHookReturn } from './useFloatingPopover';
+/**
+ * This adds additional props to the activator to handle keyboard interactions with a virtually focused item.
+ *
+ * @param {FloatingPopoverHookReturn} popover the popover context
+ * @param {HTMLAttributes<HTMLElement>} referenceProps the props of the activator, allowing them to be drilled down to the virtual reference
+ *
+ * @returns {IressUnstyledProps} the props to be passed to the floating content
+ */
+export declare const usePopoverActivatorInteractions: <E extends keyof HTMLElementTagNameMap = "div">(popover?: FloatingPopoverHookReturn, referenceProps?: Omit<IressUnstyledProps<E>, "value">) => {
+    onBlur: (e: FocusEvent<never>) => void;
+    onKeyDown: (e: KeyboardEvent<HTMLElementTagNameMap[E]>) => void;
+};

package/dist/components/Popover/hooks/usePopoverActivatorInteractions.js

@@ -1,11 +1,11 @@
-import { useCallback as s } from "react";
+import { useCallback as i } from "react";
 const c = (t, n) => {
-  const a = s(
+  const a = i(
     (e) => {
       n?.onBlur?.(e);
     },
     [n]
-  ), i = s(
+  ), s = i(
     (e) => {
       t?.show ? l(e, t) : t && o(e, t), n?.onKeyDown?.(e);
     },
@@ -13,20 +13,21 @@ const c = (t, n) => {
   );
   return {
     onBlur: a,
-    onKeyDown: i
+    onKeyDown: s
   };
 }, l = (t, n) => {
   const a = n?.getVirtualFocus !== void 0;
-  if (n?.getVirtualFocus?.()?.onKeyDown?.(t), t.key === "Tab" && (n?.getVirtualFocus?.()?.onBlur?.(t), n?.getVirtualFocus && n?.setShowWithReason(!1, t.nativeEvent, "focus")), t.key === "PageUp" && a && n.setActiveIndex(0), t.key === "PageDown" && a) {
-    const i = Math.max(n?.list.current.length - 1, 0);
-    n.setActiveIndex(i);
+  if (n?.getVirtualFocus?.()?.onKeyDown?.(t), t.key === "Tab" && (n?.getVirtualFocus?.()?.onBlur?.(t), n?.getVirtualFocus && n?.setShowWithReason(!1, t.nativeEvent, "focus")), t.key === "Escape" && n?.setShowWithReason(!1, t.nativeEvent, "escape-key"), t.key === "PageUp" && a && n.setActiveIndex(0), t.key === "PageDown" && a) {
+    const s = Math.max(n?.list.current.length - 1, 0);
+    n.setActiveIndex(s);
   }
-  if (t.key === "ArrowUp" && n?.activeIndex === 0 && n?.setShowWithReason(!1, t.nativeEvent, "focus"), t.key === "ArrowRight" && t.isDefaultPrevented() && t.target instanceof HTMLInputElement && t.target.value?.length) {
-    const i = t.target, e = i.selectionStart ?? 0;
-    e < i.value.length && i.setSelectionRange(e + 1, e + 1);
+  if (t.key === "ArrowRight" && t.isDefaultPrevented() && t.target instanceof HTMLInputElement && t.target.value?.length) {
+    const s = t.target, e = s.selectionStart ?? 0;
+    e < s.value.length && s.setSelectionRange(e + 1, e + 1);
   }
 }, o = (t, n) => {
-  t.key === "ArrowDown" && n?.setShowWithReason(!0, t.nativeEvent, "focus");
+  const a = n?.nested ? "ArrowRight" : "ArrowDown";
+  t.key === a && n?.setShowWithReason(!0, t.nativeEvent, "focus");
 };
 export {
   c as usePopoverActivatorInteractions

package/dist/components/Popover/hooks/usePopoverImperativeHandle.d.ts

@@ -0,0 +1,20 @@
+import { ForwardedRef } from 'react';
+import { FloatingPopoverHookReturn } from './useFloatingPopover';
+export interface PopoverRef extends Pick<FloatingPopoverHookReturn, 'setShow' | 'show' | 'toggleAriaControls'> {
+    /**
+     * Gets the activator element of the popover. This is the element that triggers the popover to open when interacted with. It is a div container for the activator content, and is not focusable itself (e.g., if the activator is a button inside the container).
+     * @returns {HTMLElement | null
+     */
+    getActivator: () => HTMLElement | null;
+    /**
+     * Gets the focusable activator element of the popover. This is the element that should receive focus when the popover is opened, which may be different from the activator element in some cases (e.g., a nested button inside the activator).
+     * @returns {HTMLElement | undefined}
+     */
+    getFocusableActivator?: () => HTMLElement | undefined;
+    /**
+     * Gets the content element of the popover. This is the element that contains the content of the popover, and is used for positioning and focus management.
+     * @returns {HTMLElement | null}
+     */
+    getContent: () => HTMLElement | null;
+}
+export declare const usePopoverImperativeHandle: (ref: ForwardedRef<PopoverRef>, context: FloatingPopoverHookReturn) => void;

package/dist/components/Popover/hooks/usePopoverItem.d.ts

@@ -0,0 +1,39 @@
+import { KeyboardEventHandler } from 'react';
+export interface PopoverItemHookReturn {
+    /**
+     * The id to be passed to the item.
+     * It is used to set the aria-activedescendant on virtually focused popovers, allowing screen readers to announce the active item.
+     */
+    id: string;
+    /**
+     * Whether the item is active in the popover.
+     * This is used to set the style of the item when it is active, whether virtual or not.
+     */
+    isActiveInPopover?: boolean;
+    /**
+     * The ref to be passed to the item.
+     * This is used to register the item within Floating UI, allowing it to be focused and managed by the popover.
+     */
+    ref?: (node: HTMLElement | null) => void;
+    /**
+     * The tabIndex to be passed to the item.
+     * - In virtual focus mode, this is always -1, as the item is not focusable.
+     * - In non-virtual focus mode, this is 0 if the item is active, and -1 otherwise.
+     */
+    tabIndex?: number;
+}
+export interface PopoverVirtualNode<T extends HTMLElement = HTMLElement> {
+    onBlur?: KeyboardEventHandler<T>;
+    onKeyDown?: KeyboardEventHandler<T>;
+}
+/**
+ * This is a wrapper around the useListItem hook from Floating UI, which is used to manage the focus state of the popover items.
+ * It provides the necessary props to the popover items to manage their focus state, and sets virtual focus if required.
+ *
+ * See: https://floating-ui.com/docs/FloatingList#uselistitem
+ *
+ * @param {string} typeAheadLabel the label to be used when the user is typing to navigate the activator (currently unused in IDS)
+ * @param {PopoverVirtualNode | null} virtualNode the virtual node to use when the item is focused. This contains some interactions to emulate keydown and blur on the popover item.
+ * @returns {PopoverItemHookReturn} the props to be passed to the floating content
+ */
+export declare const usePopoverItem: <T extends HTMLElement = HTMLElement>(typeAheadLabel?: string, virtualNode?: PopoverVirtualNode<T> | null) => PopoverItemHookReturn;

package/dist/components/Popover/hooks/usePopoverItem.js

@@ -1,8 +1,8 @@
-import { h as c } from "../../../floating-ui.react-BetVZ099.js";
+import { h as c } from "../../../floating-ui.react-B0nDXRN6.js";
 import { useContext as p, useId as f, useMemo as m, useEffect as v } from "react";
-import { PopoverContext as d } from "./usePopover.js";
+import { FloatingPopoverContext as a } from "./useFloatingPopover.js";
 const l = (r, t = null) => {
-  const e = p(d), { ref: s, index: n } = c({ label: r }), i = f(), o = n === e?.activeIndex, u = m(() => {
+  const e = p(a), { ref: n, index: s } = c({ label: r }), i = f(), o = s === e?.activeIndex, u = m(() => {
     if (e)
       return o && !e?.isVirtualFocus ? 0 : -1;
   }, [o, e]);
@@ -11,7 +11,7 @@ const l = (r, t = null) => {
   }, [o, e, t]), {
     id: i,
     isActiveInPopover: o,
-    ref: s,
+    ref: n,
     tabIndex: e ? u : void 0
   };
 };