@carbon-labs/react-ui-shell 0.4.0 → 0.6.0

package/es/components/HeaderPanel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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, { ReactNode } from 'react';
+export interface HeaderPanelProps {
+    /**
+     * Specify whether focus and blur listeners are added. They are by default.
+     */
+    addFocusListeners?: boolean;
+    /**
+     * The content that will render inside of the `HeaderPanel`
+     */
+    children?: ReactNode;
+    /**
+     * Optionally provide a custom class to apply to the underlying `<li>` node
+     */
+    className?: string;
+    /**
+     * Specify whether the panel is expanded
+     */
+    expanded?: boolean;
+    /**
+     * Provide the `href` to the id of the element on your package that could
+     * be target.
+     */
+    href?: string;
+    /**
+     * An optional listener that is called a callback to collapse the HeaderPanel
+     */
+    onHeaderPanelFocus?: () => void;
+}
+export declare const HeaderPanel: React.FC<HeaderPanelProps>;

package/es/components/HeaderPanel.js

@@ -0,0 +1,104 @@
+/**
+ * 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 cx from '../_virtual/index.js';
+import PropTypes from 'prop-types';
+import React, { useRef, useState } from 'react';
+import { usePrefix } from '@carbon/react/lib/internal/usePrefix';
+import { keys } from '@carbon/react/lib/internal/keyboard/keys';
+import { match } from '@carbon/react/lib/internal/keyboard/match';
+import { useWindowEvent } from '@carbon/react/lib/internal/useEvent';
+import { useMergedRefs } from '@carbon/react/lib/internal/useMergedRefs';
+
+const noopFn = () => {};
+const HeaderPanel = /*#__PURE__*/React.forwardRef(function HeaderPanel(_ref, ref) {
+  let {
+    children,
+    className: customClassName,
+    expanded,
+    addFocusListeners = true,
+    onHeaderPanelFocus = noopFn,
+    href,
+    ...rest
+  } = _ref;
+  const prefix = usePrefix();
+  const headerPanelReference = useRef(null);
+  const headerPanelRef = useMergedRefs([headerPanelReference, ref]);
+  const controlled = useRef(expanded !== undefined).current;
+  const [expandedState, setExpandedState] = useState(expanded);
+  const expandedProp = controlled ? expanded : expandedState;
+  const [lastClickedElement, setLastClickedElement] = useState(null);
+  const className = cx(`${prefix}--header-panel`, {
+    [`${prefix}--header-panel--expanded`]: expandedProp,
+    [customClassName]: !!customClassName
+  });
+  const eventHandlers = {};
+  if (addFocusListeners) {
+    eventHandlers.onBlur = event => {
+      if (!event.currentTarget.contains(event.relatedTarget) && !lastClickedElement?.classList?.contains(`${prefix}--switcher__item-link`)) {
+        setExpandedState(false);
+        setLastClickedElement(null);
+        if (expanded) {
+          onHeaderPanelFocus();
+        }
+      }
+    };
+    eventHandlers.onKeyDown = event => {
+      if (match(event, keys.Escape)) {
+        setExpandedState(false);
+        onHeaderPanelFocus();
+        if (href) {
+          window.location.href = href;
+        }
+      }
+    };
+  }
+  useWindowEvent('click', () => {
+    const focusedElement = document.activeElement;
+    setLastClickedElement(focusedElement);
+    const childJsxElement = children;
+    if (childJsxElement?.type?.displayName === 'Switcher' && !focusedElement?.closest(`.${prefix}--header-panel--expanded`) && !focusedElement?.closest(`.${prefix}--header__action`) && !headerPanelReference?.current?.classList.contains(`${prefix}--switcher`) && expanded) {
+      setExpandedState(false);
+      onHeaderPanelFocus();
+    }
+  });
+  return /*#__PURE__*/React.createElement("div", _extends({}, rest, {
+    className: className,
+    ref: headerPanelRef
+  }, eventHandlers), children);
+});
+HeaderPanel.propTypes = {
+  /**
+   * Specify whether focus and blur listeners are added. They are by default.
+   */
+  addFocusListeners: PropTypes.bool,
+  /**
+   * The content that will render inside of the `HeaderPanel`
+   */
+  children: PropTypes.any,
+  /**
+   * Optionally provide a custom class to apply to the underlying `<li>` node
+   */
+  className: PropTypes.string,
+  /**
+   * Specify whether the panel is expanded
+   */
+  expanded: PropTypes.bool,
+  /**
+   * Provide the `href` to the id of the element on your package that could
+   * be target.
+   */
+  href: PropTypes.string,
+  /**
+   * An optional listener that is called a callback to collapse the HeaderPanel
+   */
+  onHeaderPanelFocus: PropTypes.func
+};
+HeaderPanel.displayName = 'HeaderPanel';
+
+export { HeaderPanel };

package/es/components/SideNav.d.ts

@@ -5,26 +5,39 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React, { type ComponentProps, type FocusEvent, type KeyboardEvent, type MouseEventHandler } from 'react';
-export interface SideNavProps extends ComponentProps<'nav'> {
-    expanded?: boolean | undefined;
-    defaultExpanded?: boolean | undefined;
-    isChildOfHeader?: boolean | undefined;
-    onToggle?: (event: FocusEvent<HTMLElement> | KeyboardEvent<HTMLElement> | boolean, value: boolean) => void | undefined;
-    href?: string | undefined;
-    isFixedNav?: boolean | undefined;
-    isRail?: boolean | undefined;
-    isPersistent?: boolean | undefined;
-    addFocusListeners?: boolean | undefined;
-    addMouseListeners?: boolean | undefined;
-    onOverlayClick?: MouseEventHandler<HTMLDivElement> | undefined;
-    onSideNavBlur?: () => void | undefined;
+import { TranslateWithId } from '@carbon/react/lib/types/common';
+export declare enum SIDE_NAV_TYPE {
+    DEFAULT = "default",
+    RAIL = "rail",
+    PANEL = "panel"
+}
+export type TranslationKey = keyof typeof translationIds;
+export declare const translationIds: {
+    readonly 'collapse.sidenav': "collapse.sidenav";
+    readonly 'expand.sidenav': "expand.sidenav";
+};
+export interface SideNavProps extends ComponentProps<'nav'>, TranslateWithId<TranslationKey> {
+    expanded?: boolean;
+    defaultExpanded?: boolean;
+    isChildOfHeader?: boolean;
+    onToggle?: (event: FocusEvent<HTMLElement> | KeyboardEvent<HTMLElement> | boolean, value: boolean) => void;
+    href?: string;
+    isFixedNav?: boolean;
+    isRail?: boolean;
+    isPersistent?: boolean;
+    addFocusListeners?: boolean;
+    addMouseListeners?: boolean;
+    onOverlayClick?: MouseEventHandler<HTMLDivElement>;
+    onSideNavBlur?: () => void;
     enterDelayMs?: number;
     inert?: boolean;
-    isCollapsible: boolean | undefined;
-    hideOverlay: boolean | undefined;
+    isCollapsible: boolean;
+    hideOverlay: boolean;
+    navType: SIDE_NAV_TYPE;
 }
 interface SideNavContextData {
-    isRail?: boolean | undefined;
+    isRail?: boolean;
+    navType?: SIDE_NAV_TYPE;
 }
 export declare const SideNavContext: React.Context<SideNavContextData>;
 export declare const SideNav: React.ForwardRefExoticComponent<Omit<SideNavProps, "ref"> & React.RefAttributes<HTMLElement>>;

package/es/components/SideNav.js

@@ -12,17 +12,31 @@ import PropTypes from 'prop-types';
 import { AriaLabelPropType } from '@carbon/react/lib/prop-types/AriaPropTypes';
 import { CARBON_SIDENAV_ITEMS } from './_utils.js';
 import { usePrefix } from '@carbon/react/lib/internal/usePrefix';
-import { keys } from '@carbon/react/lib/internal/keyboard/keys';
+import * as keys from '@carbon/react/lib/internal/keyboard/keys';
 import { match } from '@carbon/react/lib/internal/keyboard/match';
 import { useMergedRefs } from '@carbon/react/lib/internal/useMergedRefs';
 import { useWindowEvent } from '@carbon/react/lib/internal/useEvent';
 import { useDelayedState } from '@carbon/react/lib/internal/useDelayedState';
 import { breakpoints } from '../node_modules/@carbon/layout/es/index.js';
 import { useMatchMedia } from '@carbon/react/lib/internal/useMatchMedia';
+import { SideNavToggle } from './SideNavToggle.js';
+import { SidePanelClose, SidePanelOpen } from '../node_modules/@carbon/icons-react/es/generated/bucket-15.js';
 
-// TO-DO: comment back in when footer is added for rails
-// import SideNavFooter from './SideNavFooter';
-
+let SIDE_NAV_TYPE = /*#__PURE__*/function (SIDE_NAV_TYPE) {
+  SIDE_NAV_TYPE["DEFAULT"] = "default";
+  SIDE_NAV_TYPE["RAIL"] = "rail";
+  SIDE_NAV_TYPE["PANEL"] = "panel";
+  return SIDE_NAV_TYPE;
+}({});
+const translationIds = {
+  'collapse.sidenav': 'collapse.sidenav',
+  'expand.sidenav': 'expand.sidenav'
+};
+const defaultTranslations = {
+  [translationIds['collapse.sidenav']]: 'Collapse',
+  [translationIds['expand.sidenav']]: 'Expand'
+};
+const defaultTranslateWithId = id => defaultTranslations[id];
 const SideNavContext = /*#__PURE__*/createContext({});
 function SideNavRenderFunction(_ref, ref) {
   let {
@@ -38,6 +52,7 @@ function SideNavRenderFunction(_ref, ref) {
     isFixedNav = false,
     isRail,
     isPersistent = true,
+    navType = SIDE_NAV_TYPE.DEFAULT,
     addFocusListeners = true,
     addMouseListeners = true,
     onOverlayClick,
@@ -45,6 +60,7 @@ function SideNavRenderFunction(_ref, ref) {
     enterDelayMs = 100,
     isCollapsible = false,
     hideOverlay = false,
+    translateWithId: t = defaultTranslateWithId,
     ...other
   } = _ref;
   const prefix = usePrefix();
@@ -56,6 +72,7 @@ function SideNavRenderFunction(_ref, ref) {
   const expanded = controlled ? expandedProp : expandedState;
   const sideNavRef = useRef(null);
   const navRef = useMergedRefs([sideNavRef, ref]);
+  const sideNavToggleText = expandedState ? t('collapse.sidenav') : t('expand.sidenav');
   const handleToggle = function (event) {
     let value = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : !expanded;
     if (!controlled) {
@@ -77,6 +94,7 @@ function SideNavRenderFunction(_ref, ref) {
     [`${prefix}--side-nav--expanded`]: expanded || expandedViaHoverState,
     [`${prefix}--side-nav--collapsed`]: !expanded && isFixedNav,
     [`${prefix}--side-nav--rail`]: isRail,
+    [`${prefix}--side-nav--panel`]: navType === SIDE_NAV_TYPE.PANEL,
     [`${prefix}--side-nav--ux`]: isChildOfHeader,
     [`${prefix}--side-nav--hidden`]: !isPersistent,
     [`${prefix}--side-nav--collapsible`]: isCollapsible
@@ -110,6 +128,9 @@ function SideNavRenderFunction(_ref, ref) {
       }
     };
     eventHandlers.onBlur = event => {
+      if (navType === SIDE_NAV_TYPE.PANEL) {
+        return;
+      }
       if (!event.currentTarget.contains(event.relatedTarget)) {
         handleToggle(event, false);
       }
@@ -167,7 +188,10 @@ function SideNavRenderFunction(_ref, ref) {
     ref: navRef,
     className: `${prefix}--side-nav__navigation ${className}`,
     inert: !isRail ? expanded || isLg ? undefined : -1 : undefined
-  }, accessibilityLabel, eventHandlers, other), childrenToRender));
+  }, accessibilityLabel, eventHandlers, other), childrenToRender, navType === SIDE_NAV_TYPE.PANEL && /*#__PURE__*/React.createElement(SideNavToggle, {
+    renderIcon: expandedState ? SidePanelClose : SidePanelOpen,
+    onClick: () => setExpandedState(!expandedState)
+  }, sideNavToggleText)));
 }
 const SideNav = /*#__PURE__*/React.forwardRef(SideNavRenderFunction);
 SideNav.displayName = 'SideNav';
@@ -259,4 +283,4 @@ SideNav.propTypes = {
   // translateById: PropTypes.func,
 };
 
-export { SideNav, SideNavContext };
+export { SIDE_NAV_TYPE, SideNav, SideNavContext, translationIds };

package/es/components/SideNavToggle.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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, { ReactNode } from 'react';
+interface SideNavToggleProps {
+    /**
+     * Specify the text content for the link
+     */
+    children: ReactNode;
+    /**
+     * Provide an optional function to be called when the item is clicked.
+     */
+    onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * A custom icon to render next to the SideNavToggle title. This can be a function returning JSX or JSX itself.
+     */
+    renderIcon?: React.ComponentType;
+    /**
+     * The tabIndex for the button element.
+     * If not specified, the default validation will be applied.
+     */
+    tabIndex?: number;
+}
+export declare const SideNavToggle: React.ForwardRefExoticComponent<SideNavToggleProps & React.RefAttributes<HTMLElement>>;
+export default SideNavToggle;

package/es/components/SideNavToggle.js

@@ -0,0 +1,52 @@
+/**
+ * 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 PropTypes from 'prop-types';
+import React from 'react';
+import { SideNavIcon } from '@carbon/react';
+import { usePrefix } from '@carbon/react/lib/internal/usePrefix';
+
+const SideNavToggle = /*#__PURE__*/React.forwardRef(function SideNavToggle(_ref, ref) {
+  let {
+    renderIcon: IconElement,
+    tabIndex,
+    children,
+    ...rest
+  } = _ref;
+  const prefix = usePrefix();
+  return /*#__PURE__*/React.createElement("button", _extends({
+    className: `${prefix}--side-nav__toggle`,
+    ref: ref,
+    type: "button",
+    tabIndex: tabIndex ?? 0
+  }, rest), IconElement && /*#__PURE__*/React.createElement(SideNavIcon, null, /*#__PURE__*/React.createElement(IconElement, null)), /*#__PURE__*/React.createElement("span", {
+    className: `${prefix}--side-nav__toggle-text`
+  }, children));
+});
+SideNavToggle.displayName = 'SideNavToggle';
+SideNavToggle.propTypes = {
+  /**
+   * Specify the text content for the toggle
+   */
+  children: PropTypes.element,
+  /**
+   * Provide an optional function to be called when clicked
+   */
+  onClick: PropTypes.func,
+  /**
+   * Pass in a custom icon to render next to the `SideNavToggle` title
+   */
+  // @ts-expect-error - PropTypes are unable to cover this case.
+  renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
+  /**
+   * Optional prop to specify the tabIndex of the button. If undefined, it will be applied default validation
+   */
+  tabIndex: PropTypes.number
+};
+
+export { SideNavToggle, SideNavToggle as default };

package/es/index.d.ts

@@ -7,3 +7,4 @@
  * LICENSE file in the root directory of this source tree.
  */
 export { SideNav } from './components/SideNav.js';
+export { HeaderPanel } from './components/HeaderPanel';

package/es/index.js

@@ -6,3 +6,4 @@
  */
 
 export { SideNav } from './components/SideNav.js';
+export { HeaderPanel } from './components/HeaderPanel.js';

package/es/node_modules/@carbon/icon-helpers/es/index.js

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+
+function _defineProperty(e, r, t) {
+  return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
+    value: t,
+    enumerable: !0,
+    configurable: !0,
+    writable: !0
+  }) : e[r] = t, e;
+}
+function ownKeys(e, r) {
+  var t = Object.keys(e);
+  if (Object.getOwnPropertySymbols) {
+    var o = Object.getOwnPropertySymbols(e);
+    r && (o = o.filter(function (r) {
+      return Object.getOwnPropertyDescriptor(e, r).enumerable;
+    })), t.push.apply(t, o);
+  }
+  return t;
+}
+function _objectSpread2(e) {
+  for (var r = 1; r < arguments.length; r++) {
+    var t = null != arguments[r] ? arguments[r] : {};
+    r % 2 ? ownKeys(Object(t), !0).forEach(function (r) {
+      _defineProperty(e, r, t[r]);
+    }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) {
+      Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r));
+    });
+  }
+  return e;
+}
+function _objectWithoutProperties(e, t) {
+  if (null == e) return {};
+  var o,
+    r,
+    i = _objectWithoutPropertiesLoose(e, t);
+  if (Object.getOwnPropertySymbols) {
+    var s = Object.getOwnPropertySymbols(e);
+    for (r = 0; r < s.length; r++) o = s[r], t.includes(o) || {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]);
+  }
+  return i;
+}
+function _objectWithoutPropertiesLoose(r, e) {
+  if (null == r) return {};
+  var t = {};
+  for (var n in r) if ({}.hasOwnProperty.call(r, n)) {
+    if (e.includes(n)) continue;
+    t[n] = r[n];
+  }
+  return t;
+}
+function _toPrimitive(t, r) {
+  if ("object" != typeof t || !t) return t;
+  var e = t[Symbol.toPrimitive];
+  if (void 0 !== e) {
+    var i = e.call(t, r || "default");
+    if ("object" != typeof i) return i;
+    throw new TypeError("@@toPrimitive must return a primitive value.");
+  }
+  return ("string" === r ? String : Number)(t);
+}
+function _toPropertyKey(t) {
+  var i = _toPrimitive(t, "string");
+  return "symbol" == typeof i ? i : i + "";
+}
+var _excluded = ["width", "height", "viewBox"],
+  _excluded2 = ["tabindex"];
+/**
+ * Copyright IBM Corp. 2018, 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.
+ */
+
+var defaultAttributes = {
+  // Reference:
+  // https://github.com/IBM/carbon-components-react/issues/1392
+  // https://github.com/PolymerElements/iron-iconset-svg/pull/47
+  // `focusable` is a string attribute which is why we do not use a boolean here
+  focusable: 'false',
+  preserveAspectRatio: 'xMidYMid meet'
+};
+
+/**
+ * Get supplementary HTML attributes for a given <svg> element based on existing
+ * attributes.
+ */
+function getAttributes() {
+  var _ref = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {},
+    width = _ref.width,
+    height = _ref.height,
+    _ref$viewBox = _ref.viewBox,
+    viewBox = _ref$viewBox === void 0 ? "0 0 ".concat(width, " ").concat(height) : _ref$viewBox,
+    attributes = _objectWithoutProperties(_ref, _excluded);
+  var tabindex = attributes.tabindex,
+    rest = _objectWithoutProperties(attributes, _excluded2);
+  var iconAttributes = _objectSpread2(_objectSpread2(_objectSpread2({}, defaultAttributes), rest), {}, {
+    width: width,
+    height: height,
+    viewBox: viewBox
+  });
+
+  // TODO: attributes.title assumes that the consumer will implement <title> and
+  // correctly set `aria-labelledby`.
+  if (iconAttributes['aria-label'] || iconAttributes['aria-labelledby'] || iconAttributes.title) {
+    iconAttributes.role = 'img';
+
+    // Reference:
+    // https://allyjs.io/tutorials/focusing-in-svg.html
+    if (tabindex !== undefined && tabindex !== null) {
+      iconAttributes.focusable = 'true';
+      iconAttributes.tabindex = tabindex;
+    }
+  } else {
+    iconAttributes['aria-hidden'] = true;
+  }
+  return iconAttributes;
+}
+
+export { defaultAttributes, getAttributes };

package/es/node_modules/@carbon/icons-react/es/Icon.js

@@ -0,0 +1,71 @@
+/**
+ * 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 { getAttributes } from '../../icon-helpers/es/index.js';
+import PropTypes from 'prop-types';
+import React from 'react';
+
+/**
+ * Copyright IBM Corp. 2019, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const Icon = /*#__PURE__*/React.forwardRef(function Icon(_ref, ref) {
+  let {
+    className,
+    children,
+    tabIndex,
+    xmlns = 'http://www.w3.org/2000/svg',
+    preserveAspectRatio = 'xMidYMid meet',
+    ...rest
+  } = _ref;
+  const {
+    tabindex,
+    ...attrs
+  } = getAttributes({
+    ...rest,
+    tabindex: tabIndex
+  });
+  const props = attrs;
+  if (className) {
+    props.className = className;
+  }
+  if (tabindex !== undefined && tabindex !== null) {
+    if (typeof tabindex === 'number') {
+      props.tabIndex = tabindex;
+    } else {
+      props.tabIndex = Number(tabIndex);
+    }
+  }
+  if (ref) {
+    props.ref = ref;
+  }
+  if (xmlns) {
+    props.xmlns = xmlns;
+  }
+  if (preserveAspectRatio) {
+    props.preserveAspectRatio = preserveAspectRatio;
+  }
+  return /*#__PURE__*/React.createElement('svg', props, children);
+});
+Icon.displayName = 'Icon';
+Icon.propTypes = {
+  'aria-hidden': PropTypes.oneOfType([PropTypes.bool, PropTypes.oneOf(['true', 'false'])]),
+  'aria-label': PropTypes.string,
+  'aria-labelledby': PropTypes.string,
+  children: PropTypes.node,
+  className: PropTypes.string,
+  height: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
+  preserveAspectRatio: PropTypes.string,
+  tabIndex: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
+  viewBox: PropTypes.string,
+  width: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
+  xmlns: PropTypes.string
+};
+
+export { Icon as default };