@carbon-labs/react-ui-shell 0.0.1-canary.421

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023 IBM Corp.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/es/_virtual/_commonjsHelpers.js

@@ -0,0 +1,12 @@
+/**
+ * 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 getDefaultExportFromCjs (x) {
+	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
+}
+
+export { getDefaultExportFromCjs };

package/es/_virtual/_rollupPluginBabelHelpers.js

@@ -0,0 +1,18 @@
+/**
+ * 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 _extends() {
+  return _extends = Object.assign ? Object.assign.bind() : function (n) {
+    for (var e = 1; e < arguments.length; e++) {
+      var t = arguments[e];
+      for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]);
+    }
+    return n;
+  }, _extends.apply(null, arguments);
+}
+
+export { _extends as extends };

package/es/_virtual/index.js

@@ -0,0 +1,14 @@
+/**
+ * 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 { getDefaultExportFromCjs } from './_commonjsHelpers.js';
+import { __require as requireClassnames } from '../node_modules/classnames/index.js';
+
+var classnamesExports = requireClassnames();
+var cx = /*@__PURE__*/getDefaultExportFromCjs(classnamesExports);
+
+export { cx as default };

package/es/_virtual/index2.js

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+var classnames = {exports: {}};
+
+export { classnames as __module };

package/es/components/SideNav.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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, { 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;
+    enterDelayMs?: number;
+    inert?: boolean;
+}
+interface SideNavContextData {
+    isRail?: boolean | undefined;
+}
+export declare const SideNavContext: React.Context<SideNavContextData>;
+export declare const SideNav: React.ForwardRefExoticComponent<Omit<SideNavProps, "ref"> & React.RefAttributes<HTMLElement>>;
+export {};

package/es/components/SideNav.js

@@ -0,0 +1,251 @@
+/**
+ * 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, { useRef, isValidElement, createContext } from 'react';
+import cx from '../_virtual/index.js';
+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 { 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';
+
+// TO-DO: comment back in when footer is added for rails
+// import SideNavFooter from './SideNavFooter';
+
+const SideNavContext = /*#__PURE__*/createContext({});
+function SideNavRenderFunction(_ref, ref) {
+  let {
+    expanded: expandedProp,
+    defaultExpanded = false,
+    isChildOfHeader = true,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    children,
+    onToggle,
+    className: customClassName,
+    href,
+    isFixedNav = false,
+    isRail,
+    isPersistent = true,
+    addFocusListeners = true,
+    addMouseListeners = true,
+    onOverlayClick,
+    onSideNavBlur,
+    enterDelayMs = 100,
+    ...other
+  } = _ref;
+  const prefix = usePrefix();
+  const {
+    current: controlled
+  } = useRef(expandedProp !== undefined);
+  const [expandedState, setExpandedState] = useDelayedState(defaultExpanded);
+  const [expandedViaHoverState, setExpandedViaHoverState] = useDelayedState(defaultExpanded);
+  const expanded = controlled ? expandedProp : expandedState;
+  const sideNavRef = useRef(null);
+  const navRef = useMergedRefs([sideNavRef, ref]);
+  const handleToggle = function (event) {
+    let value = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : !expanded;
+    if (!controlled) {
+      setExpandedState(value, enterDelayMs);
+    }
+    if (onToggle) {
+      onToggle(event, value);
+    }
+    if (controlled || isRail) {
+      setExpandedViaHoverState(value, enterDelayMs);
+    }
+  };
+  const accessibilityLabel = {
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy
+  };
+  const className = cx(customClassName, {
+    [`${prefix}--side-nav`]: true,
+    [`${prefix}--side-nav--expanded`]: expanded || expandedViaHoverState,
+    [`${prefix}--side-nav--collapsed`]: !expanded && isFixedNav,
+    [`${prefix}--side-nav--rail`]: isRail,
+    [`${prefix}--side-nav--ux`]: isChildOfHeader,
+    [`${prefix}--side-nav--hidden`]: !isPersistent
+  });
+  const overlayClassName = cx({
+    [`${prefix}--side-nav__overlay`]: true,
+    [`${prefix}--side-nav__overlay-active`]: expanded || expandedViaHoverState
+  });
+  let childrenToRender = children;
+
+  // Pass the expansion state as a prop, so children can update themselves to match
+  childrenToRender = React.Children.map(children, child => {
+    // if we are controlled, check for if we have hovered over or the expanded state, else just use the expanded state (uncontrolled)
+    const currentExpansionState = controlled ? expandedViaHoverState || expanded : expanded;
+    if (/*#__PURE__*/isValidElement(child)) {
+      const childJsxElement = child;
+      // avoid spreading `isSideNavExpanded` to non-Carbon UI Shell children
+      return /*#__PURE__*/React.cloneElement(childJsxElement, {
+        ...(CARBON_SIDENAV_ITEMS.includes(childJsxElement.type?.displayName ?? childJsxElement.type?.name) ? {
+          isSideNavExpanded: currentExpansionState
+        } : {})
+      });
+    }
+    return child;
+  });
+  const eventHandlers = {};
+  if (addFocusListeners) {
+    eventHandlers.onFocus = event => {
+      if (!event.currentTarget.contains(event.relatedTarget) && isRail) {
+        handleToggle(event, true);
+      }
+    };
+    eventHandlers.onBlur = event => {
+      if (!event.currentTarget.contains(event.relatedTarget)) {
+        handleToggle(event, false);
+      }
+      if (!event.currentTarget.contains(event.relatedTarget) && expanded && !isFixedNav) {
+        if (onSideNavBlur) {
+          onSideNavBlur();
+        }
+      }
+    };
+    eventHandlers.onKeyDown = event => {
+      if (match(event, keys.Escape)) {
+        handleToggle(event, false);
+        if (href) {
+          window.location.href = href;
+        }
+      }
+    };
+  }
+  if (addMouseListeners && isRail) {
+    eventHandlers.onMouseEnter = () => {
+      handleToggle(true, true);
+    };
+    eventHandlers.onMouseLeave = () => {
+      setExpandedState(false);
+      setExpandedViaHoverState(false);
+      handleToggle(false, false);
+    };
+    eventHandlers.onClick = () => {
+      //if delay is enabled, and user intentionally clicks it to see it expanded immediately
+      setExpandedState(true);
+      setExpandedViaHoverState(true);
+      handleToggle(true, true);
+    };
+  }
+  useWindowEvent('keydown', event => {
+    const focusedElement = document.activeElement;
+    if (match(event, keys.Tab) && expanded && !isFixedNav && sideNavRef.current && focusedElement?.classList.contains(`${prefix}--header__menu-toggle`) && !focusedElement.closest('nav')) {
+      sideNavRef.current.focus();
+    }
+  });
+  const lgMediaQuery = `(min-width: ${breakpoints.lg.width})`;
+  const isLg = useMatchMedia(lgMediaQuery);
+  return /*#__PURE__*/React.createElement(SideNavContext.Provider, {
+    value: {
+      isRail
+    }
+  }, isFixedNav ? null :
+  /*#__PURE__*/
+  // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+  React.createElement("div", {
+    className: overlayClassName,
+    onClick: onOverlayClick
+  }), /*#__PURE__*/React.createElement("nav", _extends({
+    tabIndex: -1,
+    ref: navRef,
+    className: `${prefix}--side-nav__navigation ${className}`,
+    inert: !isRail ? expanded || isLg ? undefined : -1 : undefined
+  }, accessibilityLabel, eventHandlers, other), childrenToRender));
+}
+const SideNav = /*#__PURE__*/React.forwardRef(SideNavRenderFunction);
+SideNav.displayName = 'SideNav';
+SideNav.propTypes = {
+  /**
+   * Required props for accessibility label on the underlying menu
+   */
+  ...AriaLabelPropType,
+  /**
+   * Specify whether focus and blur listeners are added. They are by default.
+   */
+  addFocusListeners: PropTypes.bool,
+  /**
+   * Specify whether mouse entry/exit listeners are added. They are by default.
+   */
+  addMouseListeners: PropTypes.bool,
+  /**
+   * Optionally provide a custom class to apply to the underlying `<li>` node
+   */
+  className: PropTypes.string,
+  /**
+   * If `true`, the SideNav will be open on initial render.
+   */
+  defaultExpanded: PropTypes.bool,
+  /**
+   * Specify the duration in milliseconds to delay before displaying the sidenavigation
+   */
+  enterDelayMs: PropTypes.number,
+  /**
+   * If `true`, the SideNav will be expanded, otherwise it will be collapsed.
+   * Using this prop causes SideNav to become a controled component.
+   */
+  expanded: PropTypes.bool,
+  /**
+   * Provide the `href` to the id of the element on your package that is the
+   * main content.
+   */
+  href: PropTypes.string,
+  /**
+   * Optionally provide a custom class to apply to the underlying `<li>` node
+   */
+  isChildOfHeader: PropTypes.bool,
+  /**
+   * Specify if sideNav is standalone
+   */
+  isFixedNav: PropTypes.bool,
+  /**
+   * Specify if the sideNav will be persistent above the lg breakpoint
+   */
+  isPersistent: PropTypes.bool,
+  /**
+   * Optional prop to display the side nav rail.
+   */
+  isRail: PropTypes.bool,
+  /**
+   * An optional listener that is called when the SideNav overlay is clicked
+   *
+   * @param {object} event
+   */
+  onOverlayClick: PropTypes.func,
+  /**
+   * An optional listener that is called a callback to collapse the SideNav
+   */
+
+  onSideNavBlur: PropTypes.func,
+  /**
+   * An optional listener that is called when an event that would cause
+   * toggling the SideNav occurs.
+   *
+   * @param {object} event
+   * @param {boolean} value
+   */
+  onToggle: PropTypes.func
+
+  /**
+   * Provide a custom function for translating all message ids within this
+   * component. This function will take in two arguments: the mesasge Id and the
+   * state of the component. From this, you should return a string representing
+   * the label you want displayed or read by screen readers.
+   */
+  // translateById: PropTypes.func,
+};
+
+export { SideNav, SideNavContext };

package/es/components/_utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @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.
+ */
+export const CARBON_SIDENAV_ITEMS: string[];

package/es/components/_utils.js

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+const CARBON_SIDENAV_ITEMS = ['SideNavFooter', 'SideNavHeader', 'SideNavItems', 'SideNavMenu', 'SideNavLink'];
+
+export { CARBON_SIDENAV_ITEMS };

package/es/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @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.
+ */
+export { SideNav } from './components/SideNav.js';

package/es/index.js

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export { SideNav } from './components/SideNav.js';

package/es/node_modules/@carbon/layout/es/index.js

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+
+/**
+ * Copyright IBM Corp. 2018, 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.
+ */
+
+// Convert
+// Default, Use with em() and rem() functions
+var baseFontSize = 16;
+
+/**
+ * Convert a given px unit to a rem unit
+ * @param {number} px
+ * @returns {string}
+ */
+function rem(px) {
+  return "".concat(px / baseFontSize, "rem");
+}
+
+// Breakpoint
+// Initial map of our breakpoints and their values
+var breakpoints = {
+  sm: {
+    width: rem(320),
+    columns: 4,
+    margin: '0'
+  },
+  md: {
+    width: rem(672),
+    columns: 8,
+    margin: rem(16)
+  },
+  lg: {
+    width: rem(1056),
+    columns: 16,
+    margin: rem(16)
+  },
+  xlg: {
+    width: rem(1312),
+    columns: 16,
+    margin: rem(16)
+  },
+  max: {
+    width: rem(1584),
+    columns: 16,
+    margin: rem(24)
+  }
+};
+
+export { baseFontSize, breakpoints, rem };

package/es/node_modules/classnames/index.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 { __module as classnames } from '../../_virtual/index2.js';
+
+var hasRequiredClassnames;
+function requireClassnames() {
+  if (hasRequiredClassnames) return classnames.exports;
+  hasRequiredClassnames = 1;
+  (function (module) {
+    /* global define */
+
+    (function () {
+
+      var hasOwn = {}.hasOwnProperty;
+      function classNames() {
+        var classes = '';
+        for (var i = 0; i < arguments.length; i++) {
+          var arg = arguments[i];
+          if (arg) {
+            classes = appendClass(classes, parseValue(arg));
+          }
+        }
+        return classes;
+      }
+      function parseValue(arg) {
+        if (typeof arg === 'string' || typeof arg === 'number') {
+          return arg;
+        }
+        if (typeof arg !== 'object') {
+          return '';
+        }
+        if (Array.isArray(arg)) {
+          return classNames.apply(null, arg);
+        }
+        if (arg.toString !== Object.prototype.toString && !arg.toString.toString().includes('[native code]')) {
+          return arg.toString();
+        }
+        var classes = '';
+        for (var key in arg) {
+          if (hasOwn.call(arg, key) && arg[key]) {
+            classes = appendClass(classes, key);
+          }
+        }
+        return classes;
+      }
+      function appendClass(value, newClass) {
+        if (!newClass) {
+          return value;
+        }
+        if (value) {
+          return value + ' ' + newClass;
+        }
+        return value + newClass;
+      }
+      if (module.exports) {
+        classNames.default = classNames;
+        module.exports = classNames;
+      } else {
+        window.classNames = classNames;
+      }
+    })();
+  })(classnames);
+  return classnames.exports;
+}
+
+export { requireClassnames as __require };

package/lib/_virtual/_commonjsHelpers.js

@@ -0,0 +1,14 @@
+/**
+ * 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';
+
+function getDefaultExportFromCjs (x) {
+	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
+}
+
+exports.getDefaultExportFromCjs = getDefaultExportFromCjs;

package/lib/_virtual/_rollupPluginBabelHelpers.js

@@ -0,0 +1,20 @@
+/**
+ * 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';
+
+function _extends() {
+  return _extends = Object.assign ? Object.assign.bind() : function (n) {
+    for (var e = 1; e < arguments.length; e++) {
+      var t = arguments[e];
+      for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]);
+    }
+    return n;
+  }, _extends.apply(null, arguments);
+}
+
+exports.extends = _extends;

package/lib/_virtual/index.js

@@ -0,0 +1,18 @@
+/**
+ * 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 _commonjsHelpers = require('./_commonjsHelpers.js');
+var index = require('../node_modules/classnames/index.js');
+
+var classnamesExports = index.__require();
+var cx = /*@__PURE__*/_commonjsHelpers.getDefaultExportFromCjs(classnamesExports);
+
+exports.default = cx;

package/lib/_virtual/index2.js

@@ -0,0 +1,12 @@
+/**
+ * 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';
+
+var classnames = {exports: {}};
+
+exports.__module = classnames;

package/lib/components/SideNav.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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, { 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;
+    enterDelayMs?: number;
+    inert?: boolean;
+}
+interface SideNavContextData {
+    isRail?: boolean | undefined;
+}
+export declare const SideNavContext: React.Context<SideNavContextData>;
+export declare const SideNav: React.ForwardRefExoticComponent<Omit<SideNavProps, "ref"> & React.RefAttributes<HTMLElement>>;
+export {};

package/lib/components/SideNav.js

@@ -0,0 +1,254 @@
+/**
+ * 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';
+
+var _rollupPluginBabelHelpers = require('../_virtual/_rollupPluginBabelHelpers.js');
+var React = require('react');
+var index = require('../_virtual/index.js');
+var PropTypes = require('prop-types');
+var AriaPropTypes = require('@carbon/react/lib/prop-types/AriaPropTypes');
+var _utils = require('./_utils.js');
+var usePrefix = require('@carbon/react/lib/internal/usePrefix');
+var keys = require('@carbon/react/lib/internal/keyboard/keys');
+var match = require('@carbon/react/lib/internal/keyboard/match');
+var useMergedRefs = require('@carbon/react/lib/internal/useMergedRefs');
+var useEvent = require('@carbon/react/lib/internal/useEvent');
+var useDelayedState = require('@carbon/react/lib/internal/useDelayedState');
+var index$1 = require('../node_modules/@carbon/layout/es/index.js');
+var useMatchMedia = require('@carbon/react/lib/internal/useMatchMedia');
+
+// TO-DO: comment back in when footer is added for rails
+// import SideNavFooter from './SideNavFooter';
+
+const SideNavContext = /*#__PURE__*/React.createContext({});
+function SideNavRenderFunction(_ref, ref) {
+  let {
+    expanded: expandedProp,
+    defaultExpanded = false,
+    isChildOfHeader = true,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    children,
+    onToggle,
+    className: customClassName,
+    href,
+    isFixedNav = false,
+    isRail,
+    isPersistent = true,
+    addFocusListeners = true,
+    addMouseListeners = true,
+    onOverlayClick,
+    onSideNavBlur,
+    enterDelayMs = 100,
+    ...other
+  } = _ref;
+  const prefix = usePrefix.usePrefix();
+  const {
+    current: controlled
+  } = React.useRef(expandedProp !== undefined);
+  const [expandedState, setExpandedState] = useDelayedState.useDelayedState(defaultExpanded);
+  const [expandedViaHoverState, setExpandedViaHoverState] = useDelayedState.useDelayedState(defaultExpanded);
+  const expanded = controlled ? expandedProp : expandedState;
+  const sideNavRef = React.useRef(null);
+  const navRef = useMergedRefs.useMergedRefs([sideNavRef, ref]);
+  const handleToggle = function (event) {
+    let value = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : !expanded;
+    if (!controlled) {
+      setExpandedState(value, enterDelayMs);
+    }
+    if (onToggle) {
+      onToggle(event, value);
+    }
+    if (controlled || isRail) {
+      setExpandedViaHoverState(value, enterDelayMs);
+    }
+  };
+  const accessibilityLabel = {
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy
+  };
+  const className = index.default(customClassName, {
+    [`${prefix}--side-nav`]: true,
+    [`${prefix}--side-nav--expanded`]: expanded || expandedViaHoverState,
+    [`${prefix}--side-nav--collapsed`]: !expanded && isFixedNav,
+    [`${prefix}--side-nav--rail`]: isRail,
+    [`${prefix}--side-nav--ux`]: isChildOfHeader,
+    [`${prefix}--side-nav--hidden`]: !isPersistent
+  });
+  const overlayClassName = index.default({
+    [`${prefix}--side-nav__overlay`]: true,
+    [`${prefix}--side-nav__overlay-active`]: expanded || expandedViaHoverState
+  });
+  let childrenToRender = children;
+
+  // Pass the expansion state as a prop, so children can update themselves to match
+  childrenToRender = React.Children.map(children, child => {
+    // if we are controlled, check for if we have hovered over or the expanded state, else just use the expanded state (uncontrolled)
+    const currentExpansionState = controlled ? expandedViaHoverState || expanded : expanded;
+    if (/*#__PURE__*/React.isValidElement(child)) {
+      const childJsxElement = child;
+      // avoid spreading `isSideNavExpanded` to non-Carbon UI Shell children
+      return /*#__PURE__*/React.cloneElement(childJsxElement, {
+        ...(_utils.CARBON_SIDENAV_ITEMS.includes(childJsxElement.type?.displayName ?? childJsxElement.type?.name) ? {
+          isSideNavExpanded: currentExpansionState
+        } : {})
+      });
+    }
+    return child;
+  });
+  const eventHandlers = {};
+  if (addFocusListeners) {
+    eventHandlers.onFocus = event => {
+      if (!event.currentTarget.contains(event.relatedTarget) && isRail) {
+        handleToggle(event, true);
+      }
+    };
+    eventHandlers.onBlur = event => {
+      if (!event.currentTarget.contains(event.relatedTarget)) {
+        handleToggle(event, false);
+      }
+      if (!event.currentTarget.contains(event.relatedTarget) && expanded && !isFixedNav) {
+        if (onSideNavBlur) {
+          onSideNavBlur();
+        }
+      }
+    };
+    eventHandlers.onKeyDown = event => {
+      if (match.match(event, keys.keys.Escape)) {
+        handleToggle(event, false);
+        if (href) {
+          window.location.href = href;
+        }
+      }
+    };
+  }
+  if (addMouseListeners && isRail) {
+    eventHandlers.onMouseEnter = () => {
+      handleToggle(true, true);
+    };
+    eventHandlers.onMouseLeave = () => {
+      setExpandedState(false);
+      setExpandedViaHoverState(false);
+      handleToggle(false, false);
+    };
+    eventHandlers.onClick = () => {
+      //if delay is enabled, and user intentionally clicks it to see it expanded immediately
+      setExpandedState(true);
+      setExpandedViaHoverState(true);
+      handleToggle(true, true);
+    };
+  }
+  useEvent.useWindowEvent('keydown', event => {
+    const focusedElement = document.activeElement;
+    if (match.match(event, keys.keys.Tab) && expanded && !isFixedNav && sideNavRef.current && focusedElement?.classList.contains(`${prefix}--header__menu-toggle`) && !focusedElement.closest('nav')) {
+      sideNavRef.current.focus();
+    }
+  });
+  const lgMediaQuery = `(min-width: ${index$1.breakpoints.lg.width})`;
+  const isLg = useMatchMedia.useMatchMedia(lgMediaQuery);
+  return /*#__PURE__*/React.createElement(SideNavContext.Provider, {
+    value: {
+      isRail
+    }
+  }, isFixedNav ? null :
+  /*#__PURE__*/
+  // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+  React.createElement("div", {
+    className: overlayClassName,
+    onClick: onOverlayClick
+  }), /*#__PURE__*/React.createElement("nav", _rollupPluginBabelHelpers.extends({
+    tabIndex: -1,
+    ref: navRef,
+    className: `${prefix}--side-nav__navigation ${className}`,
+    inert: !isRail ? expanded || isLg ? undefined : -1 : undefined
+  }, accessibilityLabel, eventHandlers, other), childrenToRender));
+}
+const SideNav = /*#__PURE__*/React.forwardRef(SideNavRenderFunction);
+SideNav.displayName = 'SideNav';
+SideNav.propTypes = {
+  /**
+   * Required props for accessibility label on the underlying menu
+   */
+  ...AriaPropTypes.AriaLabelPropType,
+  /**
+   * Specify whether focus and blur listeners are added. They are by default.
+   */
+  addFocusListeners: PropTypes.bool,
+  /**
+   * Specify whether mouse entry/exit listeners are added. They are by default.
+   */
+  addMouseListeners: PropTypes.bool,
+  /**
+   * Optionally provide a custom class to apply to the underlying `<li>` node
+   */
+  className: PropTypes.string,
+  /**
+   * If `true`, the SideNav will be open on initial render.
+   */
+  defaultExpanded: PropTypes.bool,
+  /**
+   * Specify the duration in milliseconds to delay before displaying the sidenavigation
+   */
+  enterDelayMs: PropTypes.number,
+  /**
+   * If `true`, the SideNav will be expanded, otherwise it will be collapsed.
+   * Using this prop causes SideNav to become a controled component.
+   */
+  expanded: PropTypes.bool,
+  /**
+   * Provide the `href` to the id of the element on your package that is the
+   * main content.
+   */
+  href: PropTypes.string,
+  /**
+   * Optionally provide a custom class to apply to the underlying `<li>` node
+   */
+  isChildOfHeader: PropTypes.bool,
+  /**
+   * Specify if sideNav is standalone
+   */
+  isFixedNav: PropTypes.bool,
+  /**
+   * Specify if the sideNav will be persistent above the lg breakpoint
+   */
+  isPersistent: PropTypes.bool,
+  /**
+   * Optional prop to display the side nav rail.
+   */
+  isRail: PropTypes.bool,
+  /**
+   * An optional listener that is called when the SideNav overlay is clicked
+   *
+   * @param {object} event
+   */
+  onOverlayClick: PropTypes.func,
+  /**
+   * An optional listener that is called a callback to collapse the SideNav
+   */
+
+  onSideNavBlur: PropTypes.func,
+  /**
+   * An optional listener that is called when an event that would cause
+   * toggling the SideNav occurs.
+   *
+   * @param {object} event
+   * @param {boolean} value
+   */
+  onToggle: PropTypes.func
+
+  /**
+   * Provide a custom function for translating all message ids within this
+   * component. This function will take in two arguments: the mesasge Id and the
+   * state of the component. From this, you should return a string representing
+   * the label you want displayed or read by screen readers.
+   */
+  // translateById: PropTypes.func,
+};
+
+exports.SideNav = SideNav;
+exports.SideNavContext = SideNavContext;

package/lib/components/_utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @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.
+ */
+export const CARBON_SIDENAV_ITEMS: string[];

package/lib/components/_utils.js

@@ -0,0 +1,12 @@
+/**
+ * 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';
+
+const CARBON_SIDENAV_ITEMS = ['SideNavFooter', 'SideNavHeader', 'SideNavItems', 'SideNavMenu', 'SideNavLink'];
+
+exports.CARBON_SIDENAV_ITEMS = CARBON_SIDENAV_ITEMS;

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @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.
+ */
+export { SideNav } from './components/SideNav.js';

package/lib/index.js

@@ -0,0 +1,14 @@
+/**
+ * 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';
+
+var SideNav = require('./components/SideNav.js');
+
+
+
+exports.SideNav = SideNav.SideNav;

package/lib/node_modules/@carbon/layout/es/index.js

@@ -0,0 +1,62 @@
+/**
+ * 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';
+
+/**
+ * Copyright IBM Corp. 2018, 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.
+ */
+
+// Convert
+// Default, Use with em() and rem() functions
+var baseFontSize = 16;
+
+/**
+ * Convert a given px unit to a rem unit
+ * @param {number} px
+ * @returns {string}
+ */
+function rem(px) {
+  return "".concat(px / baseFontSize, "rem");
+}
+
+// Breakpoint
+// Initial map of our breakpoints and their values
+var breakpoints = {
+  sm: {
+    width: rem(320),
+    columns: 4,
+    margin: '0'
+  },
+  md: {
+    width: rem(672),
+    columns: 8,
+    margin: rem(16)
+  },
+  lg: {
+    width: rem(1056),
+    columns: 16,
+    margin: rem(16)
+  },
+  xlg: {
+    width: rem(1312),
+    columns: 16,
+    margin: rem(16)
+  },
+  max: {
+    width: rem(1584),
+    columns: 16,
+    margin: rem(24)
+  }
+};
+
+exports.baseFontSize = baseFontSize;
+exports.breakpoints = breakpoints;
+exports.rem = rem;

package/lib/node_modules/classnames/index.js

@@ -0,0 +1,73 @@
+/**
+ * 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';
+
+var index = require('../../_virtual/index2.js');
+
+var hasRequiredClassnames;
+function requireClassnames() {
+  if (hasRequiredClassnames) return index.__module.exports;
+  hasRequiredClassnames = 1;
+  (function (module) {
+    /* global define */
+
+    (function () {
+
+      var hasOwn = {}.hasOwnProperty;
+      function classNames() {
+        var classes = '';
+        for (var i = 0; i < arguments.length; i++) {
+          var arg = arguments[i];
+          if (arg) {
+            classes = appendClass(classes, parseValue(arg));
+          }
+        }
+        return classes;
+      }
+      function parseValue(arg) {
+        if (typeof arg === 'string' || typeof arg === 'number') {
+          return arg;
+        }
+        if (typeof arg !== 'object') {
+          return '';
+        }
+        if (Array.isArray(arg)) {
+          return classNames.apply(null, arg);
+        }
+        if (arg.toString !== Object.prototype.toString && !arg.toString.toString().includes('[native code]')) {
+          return arg.toString();
+        }
+        var classes = '';
+        for (var key in arg) {
+          if (hasOwn.call(arg, key) && arg[key]) {
+            classes = appendClass(classes, key);
+          }
+        }
+        return classes;
+      }
+      function appendClass(value, newClass) {
+        if (!newClass) {
+          return value;
+        }
+        if (value) {
+          return value + ' ' + newClass;
+        }
+        return value + newClass;
+      }
+      if (module.exports) {
+        classNames.default = classNames;
+        module.exports = classNames;
+      } else {
+        window.classNames = classNames;
+      }
+    })();
+  })(index.__module);
+  return index.__module.exports;
+}
+
+exports.__require = requireClassnames;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@carbon-labs/react-ui-shell",
+  "version": "0.0.1-canary.421+072a73f",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "description": "Carbon Labs - Ui Shell",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/carbon-design-system/carbon-labs",
+    "directory": "src/components/UIShell"
+  },
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "files": [
+    "es",
+    "lib",
+    "scss"
+  ],
+  "scripts": {
+    "build": "node ../../../tasks/build.js",
+    "clean": "rm -rf {es,lib,scss}"
+  },
+  "devDependencies": {
+    "@carbon-labs/utilities": "canary"
+  },
+  "gitHead": "072a73f9945838a5538271fb7aa58975fc573f43"
+}

package/scss/ui-shell.scss

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+
+// Carbon setting imports
+@use '@carbon/styles/scss/theme' as *;
+@use '@carbon/styles/scss/colors' as *;
+@use '@carbon/styles/scss/spacing' as *;
+@use '@carbon/styles/scss/components/button' as *;
+
+$prefix: 'clabs' !default;
+
+.#{$prefix}--ui-shell__container {
+  padding: $spacing-01;
+  border: 1px solid $border-subtle-01;
+  inline-size: fit-content;
+}