@carbon-labs/react-ui-shell 0.3.0 → 0.5.0

package/README.md

@@ -0,0 +1,10 @@
+# @carbon-labs/react-ui-shell
+
+## <picture><source height="20" width="20" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-dark.svg"><source height="20" width="20" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"><img height="20" width="20" alt="IBM Telemetry" src="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"></picture> IBM Telemetry
+
+This package uses IBM Telemetry to collect de-identified and anonymized metrics
+data. By installing this package as a dependency you are agreeing to telemetry
+collection. To opt out, see
+[Opting out of IBM Telemetry data collection](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection).
+For more information on the data being collected, please see the
+[IBM Telemetry documentation](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics).

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/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/lib/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/lib/components/HeaderPanel.js

@@ -0,0 +1,106 @@
+/**
+ * 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 index = require('../_virtual/index.js');
+var PropTypes = require('prop-types');
+var React = require('react');
+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 useEvent = require('@carbon/react/lib/internal/useEvent');
+var useMergedRefs = require('@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.usePrefix();
+  const headerPanelReference = React.useRef(null);
+  const headerPanelRef = useMergedRefs.useMergedRefs([headerPanelReference, ref]);
+  const controlled = React.useRef(expanded !== undefined).current;
+  const [expandedState, setExpandedState] = React.useState(expanded);
+  const expandedProp = controlled ? expanded : expandedState;
+  const [lastClickedElement, setLastClickedElement] = React.useState(null);
+  const className = index.default(`${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.match(event, keys.keys.Escape)) {
+        setExpandedState(false);
+        onHeaderPanelFocus();
+        if (href) {
+          window.location.href = href;
+        }
+      }
+    };
+  }
+  useEvent.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", _rollupPluginBabelHelpers.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';
+
+exports.HeaderPanel = HeaderPanel;

package/lib/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/lib/index.js

@@ -8,7 +8,9 @@
 'use strict';
 
 var SideNav = require('./components/SideNav.js');
+var HeaderPanel = require('./components/HeaderPanel.js');
 
 
 
 exports.SideNav = SideNav.SideNav;
+exports.HeaderPanel = HeaderPanel.HeaderPanel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbon-labs/react-ui-shell",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -18,14 +18,20 @@
   "files": [
     "es",
     "lib",
-    "scss"
+    "scss",
+    "telemetry.yml"
   ],
   "scripts": {
     "build": "node ../../../tasks/build.js",
-    "clean": "rm -rf {es,lib,scss}"
+    "clean": "rm -rf {es,lib,scss}",
+    "postinstall": "ibmtelemetry --config=telemetry.yml",
+    "telemetry:config": "npx -y @ibm/telemetry-js-config-generator generate --id 5b9dce15-eeda-4b53-8683-3e3aeb599fd1 --endpoint https://www-api.ibm.com/ibm-telemetry/v1/metrics --files ./components/**/*.(tsx|js|jsx)"
   },
   "devDependencies": {
     "@carbon-labs/utilities": "canary"
   },
-  "gitHead": "e2bf601b2e8d4301fa72fdb9a5424f2ac938df14"
+  "dependencies": {
+    "@ibm/telemetry-js": "^1.9.1"
+  },
+  "gitHead": "ddd5bb7c28f78a9a143e27c2e1fdf3fb8d463708"
 }

package/scss/styles/_side-nav.scss

@@ -7,8 +7,6 @@
 
 @use '@carbon/styles/scss/utilities/convert' as convert;
 
-// $prefix: 'clabs' !default;
-// Do we want to update to clabs?
 $prefix: 'cds' !default;
 
 //----------------------------------------------------------------------------

package/telemetry.yml

@@ -0,0 +1,37 @@
+# yaml-language-server: $schema=https://unpkg.com/@ibm/telemetry-config-schema@v1/dist/config.schema.json
+
+version: 1
+projectId: 5b9dce15-eeda-4b53-8683-3e3aeb599fd1
+endpoint: https://www-api.ibm.com/ibm-telemetry/v1/metrics
+collect:
+  jsx:
+    elements:
+      allowedAttributeNames:
+        # SideNav
+        - addFocusListeners
+        - addMouseListeners
+        - className
+        - defaultExpanded
+        - enterDelayMs
+        - expanded
+        - href
+        - inert
+        - isChildOfHeader
+        - isCollapsible
+        - isFixedNav
+        - isPersistent
+        - isRail
+        - onOverlayClick
+        - onSideNavBlur
+        - onToggle
+        # React
+        - key
+        - ref
+      allowedAttributeStringValues:
+        - 'true'
+        - 'false'
+  npm:
+    dependencies: null
+  js:
+    functions: {}
+    tokens: null