carbon-react 154.0.0 → 154.1.0

package/esm/components/vertical-menu/index.d.ts

@@ -6,3 +6,4 @@ export { default as VerticalMenuFullScreen } from "./vertical-menu-full-screen/v
 export type { VerticalMenuFullScreenProps } from "./vertical-menu-full-screen/vertical-menu-full-screen.component";
 export { default as VerticalMenuTrigger } from "./vertical-menu-trigger/vertical-menu-trigger.component";
 export type { VerticalMenuTriggerProps } from "./vertical-menu-trigger/vertical-menu-trigger.component";
+export { ResponsiveVerticalMenu, ResponsiveVerticalMenuItem, ResponsiveVerticalMenuProvider, } from "./responsive-vertical-menu";

package/esm/components/vertical-menu/index.js

@@ -1,4 +1,5 @@
 export { default as VerticalMenu } from "./vertical-menu.component";
 export { default as VerticalMenuItem } from "./vertical-menu-item/vertical-menu-item.component";
 export { default as VerticalMenuFullScreen } from "./vertical-menu-full-screen/vertical-menu-full-screen.component";
-export { default as VerticalMenuTrigger } from "./vertical-menu-trigger/vertical-menu-trigger.component";
+export { default as VerticalMenuTrigger } from "./vertical-menu-trigger/vertical-menu-trigger.component";
+export { ResponsiveVerticalMenu, ResponsiveVerticalMenuItem, ResponsiveVerticalMenuProvider } from "./responsive-vertical-menu";

package/esm/components/vertical-menu/responsive-vertical-menu/__internal__/depth.context.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Provides context which can be used to dynamcally track the depth of a component
+ * in the component tree. This is useful for components that need to know their depth
+ * in the tree for styling or layout purposes.
+ */
+import React, { ReactNode } from "react";
+declare const DepthContext: React.Context<number>;
+export declare const useDepth: () => number;
+export declare const DepthProvider: ({ children, value, }: {
+    children: ReactNode;
+    value?: number | undefined;
+}) => React.JSX.Element;
+export declare const IncreaseDepth: ({ children }: {
+    children: ReactNode;
+}) => React.JSX.Element;
+export default DepthContext;

package/esm/components/vertical-menu/responsive-vertical-menu/__internal__/depth.context.js

@@ -0,0 +1,47 @@
+/* eslint-disable no-console */
+/**
+ * Provides context which can be used to dynamcally track the depth of a component
+ * in the component tree. This is useful for components that need to know their depth
+ * in the tree for styling or layout purposes.
+ */
+import React, { createContext, useContext } from "react";
+
+// Context to hold the current depth
+const DepthContext = /*#__PURE__*/createContext(0);
+
+// Hook to use the depth context
+export const useDepth = () => {
+  // Get the current context value
+  const context = useContext(DepthContext);
+
+  // If context is undefined, it means the hook is being used outside of a DepthProvider
+  /* istanbul ignore next */
+  if (context === undefined) {
+    console.error("useDepth must be used within a DepthProvider. Please ensure you are using the correct context.");
+    // Return a default value to avoid breakages
+    return -1;
+  }
+
+  // Return the current depth value
+  return context;
+};
+export const DepthProvider = ({
+  children,
+  value = 0
+}) => {
+  // Provide the current depth value to the context
+  return /*#__PURE__*/React.createElement(DepthContext.Provider, {
+    value: value
+  }, children);
+};
+export const IncreaseDepth = ({
+  children
+}) => {
+  const currentDepth = useDepth();
+
+  // Increase the depth by 1 for the children
+  return /*#__PURE__*/React.createElement(DepthContext.Provider, {
+    value: currentDepth + 1
+  }, children);
+};
+export default DepthContext;

package/esm/components/vertical-menu/responsive-vertical-menu/__internal__/focus.context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Provides context for managing focus within a menu component.
+ * This context allows for tracking expanded items, focusing on specific items,
+ * and moving focus in various directions (next, previous, parent, first child, last child).
+ */
+import React, { ReactNode, RefObject } from "react";
+interface MenuFocusContextType {
+    expandedItems: string[];
+    expandItem: (id: string, expand: boolean) => void;
+    focusedItemId: string | null;
+    getRegisteredItems: () => Array<{
+        id: string;
+        ref: RefObject<HTMLElement>;
+        parentId?: string;
+    }>;
+    focusItem: (id: string) => void;
+    moveFocus: (direction: "next" | "prev" | "parent" | "firstChild" | "lastChild") => void;
+    registerMenuItem: (id: string, ref: RefObject<HTMLElement>, parentId?: string) => void;
+}
+export declare const useMenuFocus: () => MenuFocusContextType;
+export declare const MenuFocusProvider: ({ children }: {
+    children: ReactNode;
+}) => React.JSX.Element;
+export {};

package/esm/components/vertical-menu/responsive-vertical-menu/__internal__/focus.context.js

@@ -0,0 +1,206 @@
+/* eslint-disable no-console */
+/**
+ * Provides context for managing focus within a menu component.
+ * This context allows for tracking expanded items, focusing on specific items,
+ * and moving focus in various directions (next, previous, parent, first child, last child).
+ */
+import React, { createContext, useCallback, useContext, useRef, useState } from "react";
+// Create a context for menu focus
+const MenuFocusContext = /*#__PURE__*/createContext(undefined);
+
+// Custom hook to use the MenuFocusContext
+export const useMenuFocus = () => {
+  // Get the current context value
+  const context = useContext(MenuFocusContext);
+
+  // If context is undefined, it means the hook is being used outside of a MenuFocusProvider
+  /* istanbul ignore next */
+  if (!context) {
+    console.error("useMenuFocus must be used within a MenuFocusProvider");
+    // Return a default value to avoid breakages
+    return {
+      expandedItems: [],
+      expandItem: () => {},
+      focusedItemId: null,
+      getRegisteredItems: () => [],
+      focusItem: () => {},
+      moveFocus: () => {},
+      registerMenuItem: () => {}
+    };
+  }
+
+  // Return the current context value
+  return context;
+};
+export const MenuFocusProvider = ({
+  children
+}) => {
+  // State to track expanded items
+  const [expandedItems, setExpandedItems] = useState([]);
+  // State to track the currently focused item
+  const [focusedItemId, setFocusedItemId] = useState(null);
+
+  // Ref to hold registered menu items
+  const menuItemsRef = useRef(new Map());
+
+  // Function to register a menu item
+  // This function takes an id, a ref to the item, and an optional parentId
+  // and stores the item in the menuItemsRef map.
+  // If a parentId is provided, it also updates the parent's childIds array
+  // to include the new item.
+  const registerMenuItem = useCallback((id, ref, parentId) => {
+    menuItemsRef.current.set(id, {
+      ref,
+      parentId,
+      childIds: []
+    });
+    if (parentId) {
+      const parentItem = menuItemsRef.current.get(parentId);
+      parentItem?.childIds.push(id);
+    }
+  }, []);
+
+  // Function to get all registered menu items
+  // This function returns an array of objects, each containing the id,
+  // ref, parentId, and childIds of the registered items.
+  const getRegisteredItems = useCallback(() => {
+    const items = Array.from(menuItemsRef.current.entries()).map(([id, {
+      ref,
+      parentId,
+      childIds
+    }]) => ({
+      id,
+      ref,
+      parentId,
+      childIds
+    }));
+    return items;
+  }, []);
+
+  // Function to focus on a specific menu item
+  // This function takes an id and focuses the corresponding item
+  // by calling the focus method on its ref.
+  // It also updates the focusedItemId state to the new id.
+  const focusItem = useCallback(id => {
+    const item = menuItemsRef.current.get(id);
+    /* istanbul ignore else */
+    if (item?.ref?.current) {
+      item.ref.current.focus();
+      setFocusedItemId(id);
+    }
+  }, []);
+
+  // Function to expand or collapse a menu item
+  // This function takes an id and a boolean value (expand)
+  // and updates the expandedItems state accordingly.
+  // If expand is true, it adds the id to the expandedItems array;
+  // otherwise, it removes the id from the array.
+  const expandItem = useCallback((id, expand) => {
+    if (expand) {
+      setExpandedItems(prev => [...prev, id]);
+    } else {
+      setExpandedItems(prev => prev.filter(itemId => itemId !== id));
+    }
+  }, []);
+
+  // Function to move focus in a specific direction
+  // This function takes a direction (next, prev, parent, firstChild, lastChild)
+  // and moves the focus accordingly.
+  // It uses the current focusedItemId to determine the current item
+  // and then finds the next item based on the direction.
+  // It also handles expanding/collapsing items as needed.
+  const moveFocus = useCallback(direction => {
+    /* istanbul ignore if */
+    if (!focusedItemId) return;
+
+    // Get the current item based on the focusedItemId
+    const currentItem = menuItemsRef.current.get(focusedItemId);
+
+    // If the current item is not found, return early
+    /* istanbul ignore if */
+    if (!currentItem) return;
+    let allItems = [];
+    let visibleItems = [];
+    let currentIndex = -1;
+    switch (direction) {
+      // Move focus to the parent item
+      case "parent":
+        /* istanbul ignore else */
+        if (currentItem.parentId) {
+          focusItem(currentItem.parentId);
+        }
+        break;
+
+      // Move focus to the first child
+      // If the current item has children and is not already expanded,
+      // expand it and focus on the first child
+      case "firstChild":
+        /* istanbul ignore else */
+        if (currentItem.childIds.length > 0) {
+          if (!expandedItems.includes(focusedItemId)) {
+            expandItem(focusedItemId, true);
+          }
+          focusItem(currentItem.childIds[0]);
+        }
+        break;
+
+      // Move focus to the last child
+      // Moving backwards through the menu works slightly differently:
+      // If the current item has children, get the last child. Before focusing on it,
+      // check if the last child is expanded. If it is, focus on its last child.
+      // If the last child is not expanded (i.e. it's just a link), focus on it directly.
+      case "lastChild":
+        /* istanbul ignore else */
+        if (currentItem.childIds.length > 0) {
+          const lastChild = currentItem.childIds[currentItem.childIds.length - 1];
+          /* istanbul ignore else */
+          if (lastChild) {
+            /* istanbul ignore if */
+            if (expandedItems.includes(lastChild)) {
+              const lastChildItem = getRegisteredItems().find(item => item.id === lastChild);
+              if (lastChildItem) {
+                focusItem(lastChildItem.childIds[lastChildItem.childIds.length - 1]);
+              }
+            } else {
+              focusItem(lastChild);
+            }
+          }
+        }
+        break;
+
+      // Move focus to the next or previous item
+      // This case handles both next and previous focus movement.
+      // Whilst this functionality is not currently used in the menu,
+      // it is included for completeness/future-proofing.
+      /* istanbul ignore next */
+      default:
+        allItems = Array.from(menuItemsRef.current.keys());
+        visibleItems = allItems.filter(id => {
+          const item = menuItemsRef.current.get(id);
+          if (!item || !item.parentId) return true;
+          const parentVisible = expandedItems.includes(item.parentId);
+          return parentVisible;
+        });
+        currentIndex = visibleItems.indexOf(focusedItemId);
+        if (currentIndex !== -1) {
+          const nextIndex = direction === "next" ? (currentIndex + 1) % visibleItems.length : (currentIndex - 1 + visibleItems.length) % visibleItems.length;
+          focusItem(visibleItems[nextIndex]);
+        }
+        break;
+    }
+  }, [focusedItemId, focusItem, expandedItems, expandItem, getRegisteredItems]);
+  const value = {
+    expandedItems,
+    expandItem,
+    focusedItemId,
+    focusItem,
+    getRegisteredItems,
+    registerMenuItem,
+    moveFocus
+  };
+
+  // Provide the current context value to the MenuFocusContext
+  return /*#__PURE__*/React.createElement(MenuFocusContext.Provider, {
+    value: value
+  }, children);
+};

package/esm/components/vertical-menu/responsive-vertical-menu/index.d.ts

@@ -0,0 +1,7 @@
+export { ResponsiveVerticalMenuProvider } from "./responsive-vertical-menu.context";
+export { ResponsiveVerticalMenu } from "./responsive-vertical-menu.component";
+export type { ResponsiveVerticalMenuProps } from "./responsive-vertical-menu.component";
+export { ResponsiveVerticalMenuItem } from "./responsive-vertical-menu-item";
+export type { ResponsiveVerticalMenuItemProps } from "./responsive-vertical-menu-item";
+export { ResponsiveVerticalMenuDivider } from "./responsive-vertical-menu-divider";
+export type { ResponsiveVerticalMenuDividerProps } from "./responsive-vertical-menu-divider";

package/esm/components/vertical-menu/responsive-vertical-menu/index.js

@@ -0,0 +1,4 @@
+export { ResponsiveVerticalMenuProvider } from "./responsive-vertical-menu.context";
+export { ResponsiveVerticalMenu } from "./responsive-vertical-menu.component";
+export { ResponsiveVerticalMenuItem } from "./responsive-vertical-menu-item";
+export { ResponsiveVerticalMenuDivider } from "./responsive-vertical-menu-divider";

package/esm/components/vertical-menu/responsive-vertical-menu/responsive-vertical-menu-divider/index.d.ts

@@ -0,0 +1,2 @@
+export { default as ResponsiveVerticalMenuDivider } from "./responsive-vertical-menu-divider.component";
+export type { ResponsiveVerticalMenuDividerProps } from "./responsive-vertical-menu-divider.component";

package/esm/components/vertical-menu/responsive-vertical-menu/responsive-vertical-menu-divider/index.js

@@ -0,0 +1 @@
+export { default as ResponsiveVerticalMenuDivider } from "./responsive-vertical-menu-divider.component";

package/esm/components/vertical-menu/responsive-vertical-menu/responsive-vertical-menu-divider/responsive-vertical-menu-divider.component.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import { MarginProps } from "styled-system";
+export interface ResponsiveVerticalMenuDividerProps extends MarginProps {
+}
+export declare const ResponsiveVerticalMenuDivider: (props: ResponsiveVerticalMenuDividerProps) => React.JSX.Element;
+export default ResponsiveVerticalMenuDivider;

package/esm/components/vertical-menu/responsive-vertical-menu/responsive-vertical-menu-divider/responsive-vertical-menu-divider.component.js

@@ -0,0 +1,19 @@
+import React from "react";
+import { StyledResponsiveVerticalMenuDivider, StyledHr } from "./responsive-vertical-menu-divider.style";
+import { filterStyledSystemMarginProps } from "../../../../style/utils";
+import { useDepth } from "../__internal__/depth.context";
+import { useResponsiveVerticalMenu } from "../responsive-vertical-menu.context";
+export const ResponsiveVerticalMenuDivider = props => {
+  const depth = useDepth();
+  const {
+    responsiveMode
+  } = useResponsiveVerticalMenu();
+  return /*#__PURE__*/React.createElement(StyledResponsiveVerticalMenuDivider, {
+    "data-component": "responsive-vertical-menu-divider",
+    "data-element": "responsive-vertical-menu-divider",
+    "data-role": "responsive-vertical-menu-divider",
+    depth: depth,
+    responsive: responsiveMode
+  }, /*#__PURE__*/React.createElement(StyledHr, filterStyledSystemMarginProps(props)));
+};
+export default ResponsiveVerticalMenuDivider;

package/esm/components/vertical-menu/responsive-vertical-menu/responsive-vertical-menu-divider/responsive-vertical-menu-divider.style.d.ts

@@ -0,0 +1,8 @@
+import { MarginProps } from "styled-system";
+interface StyledResponsiveVerticalMenuDividerProps {
+    depth: number;
+    responsive?: boolean;
+}
+export declare const StyledResponsiveVerticalMenuDivider: import("styled-components").StyledComponent<"div", any, StyledResponsiveVerticalMenuDividerProps, never>;
+export declare const StyledHr: import("styled-components").StyledComponent<"hr", any, MarginProps<Required<import("styled-system").Theme<import("styled-system").TLengthStyledSystem>>>, never>;
+export {};

package/esm/components/vertical-menu/responsive-vertical-menu/responsive-vertical-menu-divider/responsive-vertical-menu-divider.style.js

@@ -0,0 +1,13 @@
+import styled from "styled-components";
+import { margin } from "styled-system";
+export const StyledResponsiveVerticalMenuDivider = styled.div`
+  width: ${({
+  depth,
+  responsive
+}) => depth > 0 && responsive ? "88%" : "100%"};
+`;
+export const StyledHr = styled.hr`
+  border-color: #ffffff33;
+  border-bottom: 1px;
+  ${margin}
+`;

package/esm/components/vertical-menu/responsive-vertical-menu/responsive-vertical-menu-item/index.d.ts

@@ -0,0 +1,2 @@
+export { default as ResponsiveVerticalMenuItem } from "./responsive-vertical-menu-item.component";
+export type { ResponsiveVerticalMenuItemProps } from "./responsive-vertical-menu-item.component";

package/esm/components/vertical-menu/responsive-vertical-menu/responsive-vertical-menu-item/index.js

@@ -0,0 +1 @@
+export { default as ResponsiveVerticalMenuItem } from "./responsive-vertical-menu-item.component";

package/esm/components/vertical-menu/responsive-vertical-menu/responsive-vertical-menu-item/responsive-vertical-menu-item.component.d.ts

@@ -0,0 +1,23 @@
+import React, { ReactNode } from "react";
+import { MarginProps, PaddingProps } from "styled-system";
+import { IconType } from "../../../icon";
+interface BaseItemProps extends MarginProps, PaddingProps {
+    /** The content of the menu item. This will render the menu item as a parent menu. */
+    children?: ReactNode;
+    /** Custom icon to be displayed. Takes precedence over `icon` if both are specified. */
+    customIcon?: ReactNode;
+    /** The destination URL. Providing this will render the menu item as an anchor link. */
+    href?: string;
+    /** The Carbon icon to be displayed. Defers to `customIcon` if both are defined. */
+    icon?: IconType;
+    /** The unique identifier for the menu item. */
+    id: string;
+    /** The label for the menu item. */
+    label: string;
+}
+export interface ResponsiveVerticalMenuItemProps extends Omit<BaseItemProps, "id"> {
+    /** The unique identifier for the menu item. */
+    id?: string;
+}
+export declare const ResponsiveVerticalMenuItem: ({ children, id, label, ...props }: ResponsiveVerticalMenuItemProps) => React.JSX.Element;
+export default ResponsiveVerticalMenuItem;