@carbon-labs/react-animated-header 0.34.0 → 0.35.0

package/es/components/TasksController/TasksController.js

@@ -6,8 +6,8 @@
  */
 
 import { extends as _extends } from '../../_virtual/_rollupPluginBabelHelpers.js';
-import { SkeletonPlaceholder, Button, Dropdown } from '@carbon/react';
 import React, { useMemo } from 'react';
+import { SkeletonPlaceholder, Button, Dropdown } from '@carbon/react';
 import { usePrefix } from '../../node_modules/@carbon-labs/utilities/es/usePrefix.js';
 
 const TasksController = ({
@@ -17,54 +17,64 @@ const TasksController = ({
   selectedTileGroup,
   setSelectedTileGroup
 }) => {
+  const prefix = usePrefix();
+  const blockClass = `${prefix}--animated-header`;
+
+  /** Button overrides */
   const {
     className: buttonCustomClass,
     ...buttonOverrideProps
   } = tasksControllerConfig?.button?.propsOverrides || {};
+
+  /** Dropdown overrides */
   const {
     className: dropdownCustomClass,
     onChange: dropdownCustomOnChange,
     ...dropdownOverrideProps
   } = tasksControllerConfig?.dropdown?.propsOverrides || {};
-  const prefix = usePrefix();
-  const blockClass = `${prefix}--animated-header`;
+
+  /** Early outs */
+  if (!tasksControllerConfig?.type) return null;
+  if (isLoading || tasksControllerConfig?.isLoading) {
+    return /*#__PURE__*/React.createElement(SkeletonPlaceholder, {
+      className: `${blockClass}__task-controller-skeleton`
+    });
+  }
+
+  /** Button mode */
+  if (tasksControllerConfig?.type === 'button' && tasksControllerConfig?.button?.text) {
+    return /*#__PURE__*/React.createElement(Button, _extends({
+      className: `${blockClass}__button${buttonCustomClass ? ` ${buttonCustomClass}` : ''}`
+    }, buttonOverrideProps), tasksControllerConfig.button.text);
+  }
+
+  /** Build Dropdown props (uses top-level list/selection/setter) */
   const dropdownProps = useMemo(() => {
-    if (!allTileGroups?.length) {
-      return null;
-    }
+    if (!allTileGroups?.length) return null;
     return {
       id: `${blockClass}__header-dropdown`,
       className: `${blockClass}__header-dropdown${dropdownCustomClass ? ` ${dropdownCustomClass}` : ''}`,
       size: 'md',
       titleText: 'Label',
-      label: allTileGroups[0]?.label ?? '',
+      label: tasksControllerConfig?.dropdown?.label ?? allTileGroups[0]?.label ?? '',
       hideLabel: true,
       type: 'inline',
       items: allTileGroups,
       selectedItem: selectedTileGroup ?? undefined,
       onChange: e => {
-        setSelectedTileGroup?.(e);
+        if (e.selectedItem) {
+          setSelectedTileGroup?.({
+            selectedItem: e.selectedItem
+          });
+        }
         dropdownCustomOnChange?.(e);
       },
       'aria-label': tasksControllerConfig?.dropdown?.ariaLabel ?? 'Select a task group',
       ...dropdownOverrideProps
     };
-  }, [allTileGroups, blockClass, dropdownCustomClass, selectedTileGroup, tasksControllerConfig?.dropdown?.ariaLabel, dropdownOverrideProps, setSelectedTileGroup, dropdownCustomOnChange]);
-  if (!tasksControllerConfig?.type) {
-    return null;
-  }
-  if (isLoading || tasksControllerConfig?.isLoading) {
-    return /*#__PURE__*/React.createElement(SkeletonPlaceholder, {
-      className: `${blockClass}__task-controller-skeleton`
-    });
-  }
+  }, [allTileGroups, selectedTileGroup, setSelectedTileGroup, blockClass, dropdownCustomClass, dropdownOverrideProps, dropdownCustomOnChange, tasksControllerConfig?.dropdown?.label, tasksControllerConfig?.dropdown?.ariaLabel]);
 
-  // Button
-  if (tasksControllerConfig?.type === 'button' && tasksControllerConfig?.button?.text) {
-    return /*#__PURE__*/React.createElement(Button, _extends({
-      className: `${blockClass}__button${buttonCustomClass ? ` ${buttonCustomClass}` : ''}`
-    }, buttonOverrideProps), tasksControllerConfig.button.text);
-  }
+  /** Dropdown mode */
   if (tasksControllerConfig?.type === 'dropdown' && dropdownProps) {
     return /*#__PURE__*/React.createElement("div", {
       className: `${blockClass}__header-dropdown--container`

package/es/index.d.ts

@@ -8,9 +8,10 @@
  */
 import AnimatedHeader from './components/AnimatedHeader/AnimatedHeader';
 import { AriaLabels, TileGroup } from './components/AnimatedHeader/types';
+import HeaderAction from './components/HeaderAction/HeaderAction';
 import HeaderTitle from './components/HeaderTitle/HeaderTitle';
 import { BaseTile } from './components/Tiles/index';
 export * from './assets';
 export type { Workspace, WorkspaceSelectorConfig, } from './components/WorkspaceSelector/WorkspaceSelector';
 export type { TasksControllerConfig } from './components/TasksController/TasksController';
-export { AnimatedHeader, BaseTile, HeaderTitle, type AriaLabels, type TileGroup, };
+export { AnimatedHeader, BaseTile, HeaderAction, HeaderTitle, type AriaLabels, type TileGroup, };

package/es/index.js

@@ -6,6 +6,7 @@
  */
 
 export { default as AnimatedHeader } from './components/AnimatedHeader/AnimatedHeader.js';
+export { default as HeaderAction } from './components/HeaderAction/HeaderAction.js';
 export { default as HeaderTitle } from './components/HeaderTitle/HeaderTitle.js';
 import 'react';
 import '@carbon/react';

package/lib/__stories__/AnimatedHeader.stories.d.ts

@@ -1,3 +1,11 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2025
+ *
+ * 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 AnimatedHeader from '../components/AnimatedHeader/AnimatedHeader';
 import type { Meta } from '@storybook/react-webpack5';
 import '../components/animated-header.scss';
@@ -15124,11 +15132,68 @@ export declare const ThemeG10: {
         };
         expandButtonLabel: {
             description: string;
-            type: string;
         };
         collapseButtonLabel: {
             description: string;
-            type: string;
+        };
+        headerActionConfig: {
+            description: string;
+            control: {
+                type: string;
+                labels: {
+                    0: string;
+                    1: string;
+                    2: string;
+                };
+            };
+            options: number[];
+        };
+        contentSwitcherConfig: {
+            description: string;
+            control: {
+                type: string;
+                labels: {
+                    0: string;
+                    1: string;
+                    2: string;
+                    3: string;
+                };
+            };
+            options: number[];
+            mapping: {
+                0: null;
+                1: {
+                    ariaLabel: string;
+                    visibleCount: number;
+                    items: {
+                        id: string;
+                        text: string;
+                    }[];
+                };
+                2: {
+                    ariaLabel: string;
+                    visibleCount: number;
+                    items: {
+                        id: string;
+                        text: string;
+                    }[];
+                };
+                3: {
+                    ariaLabel: string;
+                    isLoading: boolean;
+                    visibleCount: number;
+                    items: never[];
+                };
+            };
+        };
+        contentSwitcherLowContrast: {
+            description: string;
+            control: {
+                type: string;
+            };
+            table: {
+                category: string;
+            };
         };
     };
     args: {
@@ -15152,6 +15217,9 @@ export declare const ThemeG10: {
             expandButton: string;
             tilesContainer: string;
         };
+        headerActionConfig: number;
+        contentSwitcherConfig: number;
+        contentSwitcherLowContrast: boolean;
         headerAnimation: number;
     };
 };
@@ -30276,11 +30344,68 @@ export declare const ThemeG100: {
         };
         expandButtonLabel: {
             description: string;
-            type: string;
         };
         collapseButtonLabel: {
             description: string;
-            type: string;
+        };
+        headerActionConfig: {
+            description: string;
+            control: {
+                type: string;
+                labels: {
+                    0: string;
+                    1: string;
+                    2: string;
+                };
+            };
+            options: number[];
+        };
+        contentSwitcherConfig: {
+            description: string;
+            control: {
+                type: string;
+                labels: {
+                    0: string;
+                    1: string;
+                    2: string;
+                    3: string;
+                };
+            };
+            options: number[];
+            mapping: {
+                0: null;
+                1: {
+                    ariaLabel: string;
+                    visibleCount: number;
+                    items: {
+                        id: string;
+                        text: string;
+                    }[];
+                };
+                2: {
+                    ariaLabel: string;
+                    visibleCount: number;
+                    items: {
+                        id: string;
+                        text: string;
+                    }[];
+                };
+                3: {
+                    ariaLabel: string;
+                    isLoading: boolean;
+                    visibleCount: number;
+                    items: never[];
+                };
+            };
+        };
+        contentSwitcherLowContrast: {
+            description: string;
+            control: {
+                type: string;
+            };
+            table: {
+                category: string;
+            };
         };
     };
     args: {
@@ -30304,6 +30429,9 @@ export declare const ThemeG100: {
             expandButton: string;
             tilesContainer: string;
         };
+        headerActionConfig: number;
+        contentSwitcherConfig: number;
+        contentSwitcherLowContrast: boolean;
         headerAnimation: number;
     };
     globals: {

package/lib/__stories__/data/index.d.ts

@@ -7,6 +7,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { TileGroup } from '../../components/AnimatedHeader/types';
+import type { HeaderActionConfig } from '../../components/HeaderAction/header-action.types';
 export declare const workspaceData: {
     id: string;
     label: string;
@@ -35,6 +36,28 @@ export declare const tasksControllerConfigLoading: {
     type: string;
     isLoading: boolean;
 };
+export declare const contentSwitcherConfigTwo: {
+    ariaLabel: string;
+    visibleCount: number;
+    items: {
+        id: string;
+        text: string;
+    }[];
+};
+export declare const contentSwitcherConfigThree: {
+    ariaLabel: string;
+    visibleCount: number;
+    items: {
+        id: string;
+        text: string;
+    }[];
+};
+export declare const contentSwitcherConfigLoading: {
+    ariaLabel: string;
+    isLoading: boolean;
+    visibleCount: number;
+    items: never[];
+};
 export declare const workspaceSelectorConfig: {
     allWorkspaces: {
         id: string;
@@ -55,3 +78,5 @@ export declare const workspaceSelectorConfigLoading: {
     setSelectedWorkspace: () => void;
     isLoading: boolean;
 };
+export declare const headerActionIcon: HeaderActionConfig;
+export declare const headerActionGhost: HeaderActionConfig;

package/lib/components/AnimatedHeader/AnimatedHeader.d.ts

@@ -10,12 +10,15 @@ import React from 'react';
 import { TasksControllerProps } from '../TasksController/TasksController';
 import { WorkspaceSelectorProps } from '../WorkspaceSelector/WorkspaceSelector';
 import { Tile, TileGroup, AriaLabels } from './types';
+import { type ContentSwitcherConfig } from '../ContentSwitcherSelector/ContentSwitcherSelector';
+import type { HeaderActionProps } from '../HeaderAction/header-action.types';
 /** Animated Header */
 export type AnimatedHeaderProps = {
     allTileGroups?: TileGroup[];
     ariaLabels?: AriaLabels;
     selectedTileGroup?: TileGroup;
     setSelectedTileGroup?: (e: any) => void;
+    contentSwitcherConfig?: ContentSwitcherConfig;
     description?: string;
     headerAnimation?: object;
     headerStatic?: React.JSX.Element | string;
@@ -27,6 +30,6 @@ export type AnimatedHeaderProps = {
     expandButtonLabel?: string;
     collapseButtonLabel?: string;
     tileClickHandler?: (tile: Tile) => void;
-} & TasksControllerProps & WorkspaceSelectorProps;
+} & TasksControllerProps & WorkspaceSelectorProps & HeaderActionProps;
 declare const AnimatedHeader: React.FC<AnimatedHeaderProps>;
 export default AnimatedHeader;

package/lib/components/AnimatedHeader/AnimatedHeader.js

@@ -21,6 +21,8 @@ var BaseTile = require('../Tiles/BaseTile/BaseTile.js');
 var TasksController = require('../TasksController/TasksController.js');
 var WorkspaceSelector = require('../WorkspaceSelector/WorkspaceSelector.js');
 var HeaderTitle = require('../HeaderTitle/HeaderTitle.js');
+var ContentSwitcherSelector = require('../ContentSwitcherSelector/ContentSwitcherSelector.js');
+var HeaderAction = require('../HeaderAction/HeaderAction.js');
 
 /** Animated Header */
 
@@ -35,6 +37,8 @@ const AnimatedHeader = ({
   productName = '[Product name]',
   userName,
   welcomeText,
+  contentSwitcherConfig,
+  headerActionConfig,
   tasksControllerConfig,
   workspaceSelectorConfig,
   isLoading,
@@ -128,13 +132,22 @@ const AnimatedHeader = ({
   })), /*#__PURE__*/React.createElement(react.Column, {
     sm: 4,
     md: 8,
-    lg: 16
+    lg: 16,
+    className: `${blockClass}__title-row`
+  }, /*#__PURE__*/React.createElement("div", {
+    className: `${blockClass}__title-and-actions`
   }, /*#__PURE__*/React.createElement(HeaderTitle.default, {
     userName: userName,
     welcomeText: welcomeText,
     headerExpanded: isOpen,
     ariaLabels: ariaLabels
-  })), (description || tasksControllerConfig) && /*#__PURE__*/React.createElement(react.Column, {
+  }), contentSwitcherConfig ? /*#__PURE__*/React.createElement("div", {
+    className: `${blockClass}__actions`
+  }, /*#__PURE__*/React.createElement(ContentSwitcherSelector.default, {
+    contentSwitcherConfig: contentSwitcherConfig,
+    isLoading: isLoading || contentSwitcherConfig.isLoading,
+    headerExpanded: isOpen
+  })) : null)), (description || tasksControllerConfig) && /*#__PURE__*/React.createElement(react.Column, {
     sm: 4,
     md: 8,
     lg: 4,
@@ -144,7 +157,7 @@ const AnimatedHeader = ({
   }, description && /*#__PURE__*/React.createElement("h2", {
     className: `${blockClass}__description`,
     "aria-label": ariaLabels?.description ?? `Header description`
-  }, description), /*#__PURE__*/React.createElement(TasksController.default, {
+  }, description), tasksControllerConfig && /*#__PURE__*/React.createElement(TasksController.default, {
     tasksControllerConfig: tasksControllerConfig,
     isLoading: isLoading,
     allTileGroups: allTileGroups,
@@ -194,7 +207,10 @@ const AnimatedHeader = ({
     className: `${blockClass}__button-collapse--gradient`
   }), /*#__PURE__*/React.createElement("div", {
     className: `${blockClass}__button-collapse--container`
-  }, /*#__PURE__*/React.createElement(react.Button, {
+  }, headerActionConfig ? /*#__PURE__*/React.createElement(HeaderAction.default, {
+    config: headerActionConfig,
+    headerExpanded: isOpen
+  }) : null, /*#__PURE__*/React.createElement(react.Button, {
     id: `${blockClass}__button-collapse`,
     kind: "ghost",
     renderIcon: isOpen ? iconsReact.ChevronUp : iconsReact.ChevronDown,
@@ -222,6 +238,24 @@ AnimatedHeader.propTypes = {
    * Custom collapse button label
    */
   collapseButtonLabel: PropTypes.string,
+  /**
+   *  Configuration for Carbon Content Switcher in header.
+   * Customized tasks are used to allow users that have multiple roles and
+   * permissions to experience better tailored content based on their need.
+   */
+  contentSwitcherConfig: PropTypes.shape({
+    items: PropTypes.arrayOf(PropTypes.shape({
+      id: PropTypes.string,
+      text: PropTypes.string.isRequired,
+      onSelect: PropTypes.func
+    }).isRequired).isRequired,
+    ariaLabel: PropTypes.string,
+    isLoading: PropTypes.bool,
+    lowContrast: PropTypes.bool,
+    headerExpanded: PropTypes.bool,
+    visibleCount: PropTypes.oneOf([2, 3]),
+    onChange: PropTypes.func
+  }),
   /**
    * Provide short sentence in max. 3 lines related to product context
    */
@@ -230,6 +264,34 @@ AnimatedHeader.propTypes = {
    * Custom expand button label
    */
   expandButtonLabel: PropTypes.string,
+  /**
+   * Configuration for the header action control (icon button / ghost button / carousel - *coming soon*).
+   * This sits to the left of the Collapse button and can trigger generic actions
+   * (open modal/panel) or page through tiles.
+   */
+  headerActionConfig: PropTypes.shape({
+    type: PropTypes.oneOf(['icon-button', 'ghost-button']).isRequired,
+    // Carbon IconButton variant
+    iconButton: PropTypes.shape({
+      icon: PropTypes.elementType.isRequired,
+      iconLabel: PropTypes.string.isRequired,
+      onClick: PropTypes.func.isRequired,
+      disabled: PropTypes.bool,
+      ariaLabel: PropTypes.string,
+      // Override Carbon IconButton props if needed
+      propsOverrides: PropTypes.object
+    }),
+    // Carbon Ghost Button variant
+    ghostButton: PropTypes.shape({
+      label: PropTypes.string.isRequired,
+      icon: PropTypes.elementType,
+      onClick: PropTypes.func.isRequired,
+      disabled: PropTypes.bool,
+      ariaLabel: PropTypes.string,
+      // Override Carbon Button props if needed
+      propsOverrides: PropTypes.object
+    })
+  }),
   /**
    * In-product imagery / lottie animation (.json) dim. 1312 x 738
    * (to update headerAnimation content storybook requires remount in toolbar)
@@ -258,23 +320,21 @@ AnimatedHeader.propTypes = {
    */
   setSelectedTileGroup: PropTypes.func,
   /**
-   * Configuration for Carbon button or dropdown menu in header. Customized
-   * tasks are used to allow users that have multiple roles and permissions
-   * to experience better tailored content based on their need.
-   * It also allows to override Carbon Button props by specifying them in tasksConfig.button.propsOverrides
-   * or to override Carbon Dropdown props by specifying them in tasksConfig.dropdown.propsOverrides.
+   * Configuration for Carbon button / dropdown in header.
+   * Customized tasks are used to allow users that have multiple roles and
+   * permissions to experience better tailored content based on their need.
    */
   tasksControllerConfig: PropTypes.shape({
     type: PropTypes.oneOf(['button', 'dropdown']).isRequired,
+    isLoading: PropTypes.bool,
     button: PropTypes.shape({
       text: PropTypes.string.isRequired,
       // Override Carbon Button props
       propsOverrides: PropTypes.object
     }),
     dropdown: PropTypes.shape({
-      allTileGroups: PropTypes.arrayOf(PropTypes.object),
-      selectedTileGroup: PropTypes.object,
-      setSelectedTileGroup: PropTypes.func.isRequired,
+      label: PropTypes.string,
+      ariaLabel: PropTypes.string,
       // Override Carbon Dropdown props
       propsOverrides: PropTypes.object
     })

package/lib/components/ContentSwitcherSelector/ContentSwitcherSelector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2025
+ *
+ * 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';
+import { type ContentSwitcherProps } from '@carbon/react';
+export type ContentSwitcherItem = {
+    id?: string;
+    text: string;
+    onSelect?: () => void;
+};
+export type ContentSwitcherConfig = Omit<ContentSwitcherProps, 'children' | 'onChange' | 'size' | 'lowContrast'> & {
+    items: ContentSwitcherItem[];
+    ariaLabel?: string;
+    isLoading?: boolean;
+    lowContrast?: boolean;
+    visibleCount?: 2 | 3;
+    onChange?: ContentSwitcherProps['onChange'];
+};
+export type ContentSwitcherSelectorProps = {
+    contentSwitcherConfig?: ContentSwitcherConfig | null;
+    isLoading?: boolean;
+    headerExpanded?: boolean;
+};
+declare const ContentSwitcherSelector: React.FC<ContentSwitcherSelectorProps>;
+export default ContentSwitcherSelector;

package/lib/components/ContentSwitcherSelector/ContentSwitcherSelector.js

@@ -0,0 +1,74 @@
+/**
+ * Copyright IBM Corp. 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _rollupPluginBabelHelpers = require('../../_virtual/_rollupPluginBabelHelpers.js');
+var React = require('react');
+var react = require('@carbon/react');
+var usePrefix = require('../../node_modules/@carbon-labs/utilities/es/usePrefix.js');
+
+const ContentSwitcherSelector = ({
+  contentSwitcherConfig,
+  isLoading,
+  headerExpanded
+}) => {
+  const prefix = usePrefix.usePrefix();
+  const blockClass = `${prefix}--animated-header__content-switcher`;
+  if (!contentSwitcherConfig) return null;
+  if (isLoading || contentSwitcherConfig.isLoading) {
+    return /*#__PURE__*/React.createElement(react.SkeletonPlaceholder, {
+      className: `${blockClass}-skeleton`
+    });
+  }
+  const {
+    items = [],
+    visibleCount,
+    lowContrast,
+    ariaLabel,
+    onChange,
+    selectedIndex,
+    ...rest
+  } = contentSwitcherConfig;
+  const count = visibleCount === 3 ? 3 : 2;
+  const visibleItems = items.slice(0, count);
+  if (visibleItems.length < 2 || visibleItems.length > 3) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn('[ContentSwitcherSelector] contentSwitcherConfig.items must contain 2 or 3 items.');
+    }
+    return null;
+  }
+  const selectedIndexSafe = React.useMemo(() => {
+    const idx = typeof selectedIndex === 'number' ? selectedIndex : 0;
+    return Math.min(Math.max(idx, 0), visibleItems.length - 1);
+  }, [selectedIndex, visibleItems.length]);
+  return /*#__PURE__*/React.createElement("div", {
+    className: `${blockClass}--container`,
+    "data-expanded": headerExpanded
+  }, /*#__PURE__*/React.createElement(react.ContentSwitcher, _rollupPluginBabelHelpers.extends({
+    className: `${blockClass}`,
+    "aria-label": ariaLabel ?? 'Select a task group',
+    lowContrast: lowContrast,
+    selectedIndex: selectedIndexSafe,
+    size: "md",
+    onChange: ev => {
+      onChange?.(ev);
+      const idx = ev.index ?? ev.selectedIndex ?? 0;
+      visibleItems[idx]?.onSelect?.();
+    }
+  }, rest), visibleItems.map((item, idx) => {
+    return /*#__PURE__*/React.createElement(react.Switch, {
+      key: item.id ?? idx,
+      name: `option-${idx}`,
+      text: item.text
+    });
+  })));
+};
+
+exports.default = ContentSwitcherSelector;

package/lib/components/HeaderAction/HeaderAction.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2025
+ *
+ * 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';
+import type { HeaderActionConfig } from './header-action.types';
+declare const HeaderAction: React.FC<{
+    config: HeaderActionConfig;
+    headerExpanded: boolean;
+}>;
+export default HeaderAction;