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

package/es/__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/es/__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/es/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/es/components/AnimatedHeader/AnimatedHeader.js

@@ -17,6 +17,8 @@ import { BaseTile } from '../Tiles/BaseTile/BaseTile.js';
 import TasksController from '../TasksController/TasksController.js';
 import WorkspaceSelector from '../WorkspaceSelector/WorkspaceSelector.js';
 import HeaderTitle from '../HeaderTitle/HeaderTitle.js';
+import ContentSwitcherSelector from '../ContentSwitcherSelector/ContentSwitcherSelector.js';
+import HeaderAction from '../HeaderAction/HeaderAction.js';
 
 /** Animated Header */
 
@@ -31,6 +33,8 @@ const AnimatedHeader = ({
   productName = '[Product name]',
   userName,
   welcomeText,
+  contentSwitcherConfig,
+  headerActionConfig,
   tasksControllerConfig,
   workspaceSelectorConfig,
   isLoading,
@@ -124,13 +128,22 @@ const AnimatedHeader = ({
   })), /*#__PURE__*/React.createElement(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, {
     userName: userName,
     welcomeText: welcomeText,
     headerExpanded: isOpen,
     ariaLabels: ariaLabels
-  })), (description || tasksControllerConfig) && /*#__PURE__*/React.createElement(Column, {
+  }), contentSwitcherConfig ? /*#__PURE__*/React.createElement("div", {
+    className: `${blockClass}__actions`
+  }, /*#__PURE__*/React.createElement(ContentSwitcherSelector, {
+    contentSwitcherConfig: contentSwitcherConfig,
+    isLoading: isLoading || contentSwitcherConfig.isLoading,
+    headerExpanded: isOpen
+  })) : null)), (description || tasksControllerConfig) && /*#__PURE__*/React.createElement(Column, {
     sm: 4,
     md: 8,
     lg: 4,
@@ -140,7 +153,7 @@ const AnimatedHeader = ({
   }, description && /*#__PURE__*/React.createElement("h2", {
     className: `${blockClass}__description`,
     "aria-label": ariaLabels?.description ?? `Header description`
-  }, description), /*#__PURE__*/React.createElement(TasksController, {
+  }, description), tasksControllerConfig && /*#__PURE__*/React.createElement(TasksController, {
     tasksControllerConfig: tasksControllerConfig,
     isLoading: isLoading,
     allTileGroups: allTileGroups,
@@ -190,7 +203,10 @@ const AnimatedHeader = ({
     className: `${blockClass}__button-collapse--gradient`
   }), /*#__PURE__*/React.createElement("div", {
     className: `${blockClass}__button-collapse--container`
-  }, /*#__PURE__*/React.createElement(Button, {
+  }, headerActionConfig ? /*#__PURE__*/React.createElement(HeaderAction, {
+    config: headerActionConfig,
+    headerExpanded: isOpen
+  }) : null, /*#__PURE__*/React.createElement(Button, {
     id: `${blockClass}__button-collapse`,
     kind: "ghost",
     renderIcon: isOpen ? ChevronUp : ChevronDown,
@@ -218,6 +234,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
    */
@@ -226,6 +260,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)
@@ -254,23 +316,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/es/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/es/components/ContentSwitcherSelector/ContentSwitcherSelector.js

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+
+import { extends as _extends } from '../../_virtual/_rollupPluginBabelHelpers.js';
+import React, { useMemo } from 'react';
+import { SkeletonPlaceholder, ContentSwitcher, Switch } from '@carbon/react';
+import { usePrefix } from '../../node_modules/@carbon-labs/utilities/es/usePrefix.js';
+
+const ContentSwitcherSelector = ({
+  contentSwitcherConfig,
+  isLoading,
+  headerExpanded
+}) => {
+  const prefix = usePrefix();
+  const blockClass = `${prefix}--animated-header__content-switcher`;
+  if (!contentSwitcherConfig) return null;
+  if (isLoading || contentSwitcherConfig.isLoading) {
+    return /*#__PURE__*/React.createElement(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 = 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(ContentSwitcher, _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(Switch, {
+      key: item.id ?? idx,
+      name: `option-${idx}`,
+      text: item.text
+    });
+  })));
+};
+
+export { ContentSwitcherSelector as default };

package/es/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;

package/es/components/HeaderAction/HeaderAction.js

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+
+import React from 'react';
+import { IconButton, Button } from '@carbon/react';
+import { usePrefix } from '../../node_modules/@carbon-labs/utilities/es/usePrefix.js';
+
+const HeaderAction = ({
+  config,
+  headerExpanded
+}) => {
+  const prefix = usePrefix();
+  const blockClass = `${prefix}--animated-header__header-action`;
+
+  // ICON
+  if (config.type === 'icon-button') {
+    const {
+      icon: Icon,
+      iconLabel,
+      onClick,
+      disabled,
+      ariaLabel
+    } = config;
+    return /*#__PURE__*/React.createElement("div", {
+      className: blockClass,
+      "aria-label": ariaLabel,
+      "aria-hidden": !headerExpanded,
+      "data-expanded": headerExpanded
+    }, /*#__PURE__*/React.createElement(IconButton, {
+      kind: "ghost",
+      size: "lg",
+      label: iconLabel,
+      onClick: onClick,
+      disabled: disabled
+    }, Icon && /*#__PURE__*/React.createElement(Icon, {
+      fill: `var(--cds-icon-secondary)`,
+      size: 16
+    })));
+  }
+
+  // GHOST
+  if (config.type === 'ghost-button') {
+    const {
+      label,
+      icon,
+      onClick,
+      disabled,
+      ariaLabel
+    } = config;
+    return /*#__PURE__*/React.createElement("div", {
+      className: blockClass,
+      "aria-label": ariaLabel,
+      "aria-hidden": !headerExpanded,
+      "data-expanded": headerExpanded
+    }, /*#__PURE__*/React.createElement(Button, {
+      kind: "ghost",
+      size: "lg",
+      onClick: onClick,
+      disabled: disabled,
+      renderIcon: icon
+    }, label));
+  }
+};
+
+export { HeaderAction as default };

package/es/components/HeaderAction/header-action.types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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 { ElementType } from 'react';
+type Base = {
+    ariaLabel?: string;
+    headerExpanded?: boolean;
+};
+export type HeaderActionIcon = Base & {
+    type: 'icon-button';
+    icon: ElementType;
+    iconLabel: string;
+    onClick: () => void;
+    disabled?: boolean;
+};
+export type HeaderActionGhost = Base & {
+    type: 'ghost-button';
+    label: string;
+    icon?: ElementType;
+    onClick: () => void;
+    disabled?: boolean;
+};
+export type HeaderActionConfig = HeaderActionIcon | HeaderActionGhost;
+export type HeaderActionProps = {
+    headerActionConfig?: HeaderActionConfig | null;
+};
+export {};

package/es/components/HeaderTitle/HeaderTitle.js

@@ -31,13 +31,12 @@ const HeaderTitle = ({
   const blockClass = `${prefix}--animated-header__title`;
   const currentLang = typeof window !== 'undefined' ? document.documentElement.lang || 'en' : 'en';
   const isNameFirst = NAME_FIRST_LANGS.includes(currentLang.slice(0, 2));
-  const headingCollapsed = `${blockClass}-collapsed`;
-  const headingExpanded = `${blockClass}-expanded`;
   return /*#__PURE__*/React.createElement(Tooltip, {
     align: "bottom",
     label: `${welcomeText}, ${userName}`
   }, /*#__PURE__*/React.createElement("h1", {
-    className: `${blockClass} ${headerExpanded ? headingExpanded : headingCollapsed}`,
+    className: blockClass,
+    "data-expanded": headerExpanded,
     "aria-label": ariaLabels?.welcome ?? `${welcomeText}, ${userName}`
   }, isNameFirst ? /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement("span", {
     className: `${blockClass}-first`

package/es/components/TasksController/TasksController.d.ts

@@ -17,6 +17,7 @@ export interface TasksControllerConfig {
     };
     dropdown?: {
         propsOverrides?: Partial<Omit<DropdownProps<TileGroup>, 'id' | 'items' | 'selectedItem'>>;
+        label?: string;
         ariaLabel?: string;
     };
 }
@@ -25,7 +26,9 @@ export type TasksControllerProps = {
     isLoading?: boolean;
     allTileGroups?: TileGroup[];
     selectedTileGroup?: TileGroup | null;
-    setSelectedTileGroup: (e: any) => void;
+    setSelectedTileGroup?: (group: TileGroup | {
+        selectedItem: TileGroup;
+    }) => void;
 };
 declare const TasksController: ({ tasksControllerConfig, isLoading, allTileGroups, selectedTileGroup, setSelectedTileGroup, }: TasksControllerProps) => import("react/jsx-runtime").JSX.Element | null;
 export default TasksController;