@carbon-labs/react-ui-shell 0.12.0 → 0.13.0

package/es/internal/keyboard/match.js

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ */
+
+/* eslint-disable jsdoc/require-param-description */
+/* eslint-disable jsdoc/require-jsdoc */
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+
+/**
+ * @typedef Key
+ * @property key {Array<string>|string}
+ * @property which {number}
+ * @property keyCode {number}
+ */
+
+/**
+ * Check to see if at least one key code matches the key code of the
+ * given event.
+ *
+ * @example
+ * import * as keys from '../keys';
+ * import { matches } from '../match';
+ *
+ * function handleOnKeyDown(event) {
+ *   if (matches(event, [keys.Enter, keys.Space]) {
+ *     // ...
+ *   }
+ * }
+ *
+ * @param {Event|React.SyntheticEvent} event
+ * @param {Array<Key>} keysToMatch
+ * @returns {boolean}
+ */
+function matches(event, keysToMatch) {
+  for (let i = 0; i < keysToMatch.length; i++) {
+    if (match(event, keysToMatch[i])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Check to see if the given key matches the corresponding keyboard event. Also
+ * supports passing in the value directly if you can't used the given event.
+ *
+ * @example
+ * import * as keys from '../keys';
+ * import { matches } from '../match';
+ *
+ * function handleOnKeyDown(event) {
+ *   if (match(event, keys.Enter) {
+ *     // ...
+ *   }
+ * }
+ *
+ * @param {React.SyntheticEvent|Event|number|string} eventOrCode
+ * @param {Key} key
+ * @returns {boolean}
+ */
+function match(eventOrCode) {
+  let {
+    key,
+    which,
+    keyCode,
+    code
+  } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  if (typeof eventOrCode === 'string') {
+    return eventOrCode === key;
+  }
+  if (typeof eventOrCode === 'number') {
+    return eventOrCode === which || eventOrCode === keyCode;
+  }
+  if (eventOrCode.key && Array.isArray(key)) {
+    return key.indexOf(eventOrCode.key) !== -1;
+  }
+  return eventOrCode.key === key || eventOrCode.which === which || eventOrCode.keyCode === keyCode || eventOrCode.code === code;
+}
+
+export { match, matches };

package/es/internal/keyboard/navigation.d.ts

@@ -0,0 +1,19 @@
+export function getNextIndex(key: string, index: number, arrayLength: number): number | undefined;
+/**
+ * A flag `node.compareDocumentPosition(target)` returns,
+ * that indicates `target` is located earlier than `node` in the document or `target` contains `node`.
+ */
+export const DOCUMENT_POSITION_BROAD_PRECEDING: number | false;
+/**
+ * A flag `node.compareDocumentPosition(target)` returns,
+ * that indicates `target` is located later than `node` in the document or `node` contains `target`.
+ */
+export const DOCUMENT_POSITION_BROAD_FOLLOWING: number | false;
+/**
+ * CSS selector that selects major nodes that are sequential-focusable.
+ */
+export const selectorTabbable: "\n  a[href], area[href], input:not([disabled]):not([tabindex='-1']),\n  button:not([disabled]):not([tabindex='-1']),select:not([disabled]):not([tabindex='-1']),\n  textarea:not([disabled]):not([tabindex='-1']),\n  iframe, object, embed, *[tabindex]:not([tabindex='-1']):not([disabled]), *[contenteditable=true]\n";
+/**
+ * CSS selector that selects major nodes that are click focusable
+ */
+export const selectorFocusable: "\n  a[href], area[href], input:not([disabled]),\n  button:not([disabled]),select:not([disabled]),\n  textarea:not([disabled]),\n  iframe, object, embed, *[tabindex]:not([disabled]), *[contenteditable=true]\n";

package/es/internal/useDelayedState.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+import { SetStateAction } from 'react';
+/**
+ * `useDelayedState` mirrors `useState` but also allows you to add a delay to
+ * when your state updates. You can provide a second argument to `setState`,
+ * `delayMs`, which will be the time in milliseconds after which the state is
+ * updated.
+ *
+ * This hook will clean up pending timers in `useEffect` and will cancel any
+ * pending timers when a `setState` is called before the state is updated from
+ * a previous call
+ */
+export type DispatchWithDelay<A> = (value: A, delayMS?: number) => void;
+export declare function useDelayedState<S>(initialState: S): [S, DispatchWithDelay<SetStateAction<S>>];

package/es/internal/useDelayedState.js

@@ -0,0 +1,56 @@
+/**
+ * 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 { useState, useRef, useCallback, useEffect } from 'react';
+
+/* eslint-disable jsdoc/require-jsdoc */
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+
+
+/**
+ * `useDelayedState` mirrors `useState` but also allows you to add a delay to
+ * when your state updates. You can provide a second argument to `setState`,
+ * `delayMs`, which will be the time in milliseconds after which the state is
+ * updated.
+ *
+ * This hook will clean up pending timers in `useEffect` and will cancel any
+ * pending timers when a `setState` is called before the state is updated from
+ * a previous call
+ */
+
+function useDelayedState(initialState) {
+  const [state, setState] = useState(initialState);
+  const timeoutId = useRef(null);
+  // We use `useCallback` to match the signature of React's `useState` which will
+  // always return the same reference for the `setState` updater
+  const setStateWithDelay = useCallback(function (stateToSet) {
+    let delayMs = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
+    window.clearTimeout(timeoutId.current ?? undefined);
+    timeoutId.current = null;
+    if (delayMs === 0) {
+      setState(stateToSet);
+      return;
+    }
+    timeoutId.current = window.setTimeout(() => {
+      setState(stateToSet);
+      timeoutId.current = null;
+    }, delayMs);
+  }, []);
+  useEffect(() => {
+    return () => {
+      window.clearTimeout(timeoutId.current ?? undefined);
+    };
+  }, []);
+  return [state, setStateWithDelay];
+}
+
+export { useDelayedState };

package/es/internal/useEvent.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @template {keyof GlobalEventHandlersEventMap} E
+ * @typedef {(event: GlobalEventHandlersEventMap[E]) => void} GlobalEventCallback
+ */
+/**
+ * @template T
+ * @typedef {import('react').MutableRefObject<T>} MutableRefObject<T>
+ */
+/**
+ * @template {keyof GlobalEventHandlersEventMap} E
+ * @param {HTMLElement | MutableRefObject<HTMLElement | null>} elementOrRef
+ * @param {E} eventName
+ * @param {GlobalEventCallback<E>} callback
+ */
+export function useEvent<E extends keyof GlobalEventHandlersEventMap>(elementOrRef: HTMLElement | MutableRefObject<HTMLElement | null>, eventName: E, callback: GlobalEventCallback<E>): void;
+/**
+ * @template {keyof WindowEventMap} E
+ * @typedef {(event: WindowEventMap[E]) => void} WindowEventCallback
+ */
+/**
+ * @template {keyof WindowEventMap} E
+ * @param {E} eventName
+ * @param {WindowEventCallback<E>} callback
+ */
+export function useWindowEvent<E extends keyof WindowEventMap>(eventName: E, callback: WindowEventCallback<E>): void;
+export type GlobalEventCallback<E extends keyof GlobalEventHandlersEventMap> = (event: GlobalEventHandlersEventMap[E]) => void;
+/**
+ * <T>
+ */
+export type MutableRefObject<T> = import('react').MutableRefObject<T>;
+export type WindowEventCallback<E extends keyof WindowEventMap> = (event: WindowEventMap[E]) => void;

package/es/internal/useEvent.js

@@ -0,0 +1,55 @@
+/**
+ * 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 { useRef, useEffect } from 'react';
+
+/* eslint-disable jsdoc/require-param-description */
+// @ts-check
+/* eslint-disable jsdoc/check-tag-names */
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+
+
+/**
+ * @template {keyof WindowEventMap} E
+ * @typedef {(event: WindowEventMap[E]) => void} WindowEventCallback
+ */
+
+/**
+ * @template {keyof WindowEventMap} E
+ * @param {E} eventName
+ * @param {WindowEventCallback<E>} callback
+ */
+function useWindowEvent(eventName, callback) {
+  /**
+   * @type {MutableRefObject<WindowEventCallback<E> | null>}
+   */
+  const savedCallback = useRef(null);
+  useEffect(() => {
+    savedCallback.current = callback;
+  }, [callback]);
+  useEffect(() => {
+    /**
+     * @type {WindowEventCallback<E>}
+     */
+    function handler(event) {
+      if (savedCallback.current) {
+        savedCallback.current(event);
+      }
+    }
+    window.addEventListener(eventName, handler);
+    return () => {
+      window.removeEventListener(eventName, handler);
+    };
+  }, [eventName]);
+}
+
+export { useWindowEvent };

package/es/internal/useMatchMedia.d.ts

@@ -0,0 +1 @@
+export function useMatchMedia(mediaQueryString: any): boolean;

package/es/internal/useMatchMedia.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 { useState, useEffect } from 'react';
+import { canUseDOM } from './environment.js';
+
+/* eslint-disable jsdoc/require-jsdoc */
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+
+function useMatchMedia(mediaQueryString) {
+  const [matches, setMatches] = useState(() => {
+    if (canUseDOM) {
+      const mediaQueryList = window.matchMedia(mediaQueryString);
+      return mediaQueryList.matches;
+    }
+    return false;
+  });
+  useEffect(() => {
+    function listener(event) {
+      setMatches(event.matches);
+    }
+    const mediaQueryList = window.matchMedia(mediaQueryString);
+    // Support fallback to `addListener` for broader browser support
+    if (mediaQueryList.addEventListener) {
+      mediaQueryList.addEventListener('change', listener);
+    } else {
+      mediaQueryList.addListener(listener);
+    }
+
+    // Make sure the media query list is in sync with the matches state
+    setMatches(mediaQueryList.matches);
+    return () => {
+      if (mediaQueryList.addEventListener) {
+        mediaQueryList.removeEventListener('change', listener);
+      } else {
+        mediaQueryList.removeListener(listener);
+      }
+    };
+  }, [mediaQueryString]);
+  return matches;
+}
+
+export { useMatchMedia };

package/es/internal/useMergedRefs.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+import { Ref, ForwardedRef } from 'react';
+/**
+ * Combine multiple refs into a single ref. This use useful when you have two
+ * refs from both `React.forwardRef` and `useRef` that you would like to add to
+ * the same node.
+ */
+export declare const useMergedRefs: <T extends unknown>(refs: ForwardedRef<T>[]) => Ref<T>;

package/es/internal/useMergedRefs.js

@@ -0,0 +1,38 @@
+/**
+ * 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 { useCallback } from 'react';
+
+/* eslint-disable @typescript-eslint/no-unnecessary-type-constraint */
+/* eslint-disable jsdoc/require-param */
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+
+
+/**
+ * Combine multiple refs into a single ref. This use useful when you have two
+ * refs from both `React.forwardRef` and `useRef` that you would like to add to
+ * the same node.
+ */
+const useMergedRefs = refs => {
+  return useCallback(node => {
+    refs.forEach(ref => {
+      if (typeof ref === 'function') {
+        ref(node);
+      } else if (ref !== null && ref !== undefined) {
+        ref.current = node;
+      }
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, refs);
+};
+
+export { useMergedRefs };

package/es/internal/usePrefix.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+import React from 'react';
+export declare const PrefixContext: React.Context<string>;
+export declare function usePrefix(): string;

package/es/internal/usePrefix.js

@@ -0,0 +1,23 @@
+/**
+ * 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';
+
+/* eslint-disable jsdoc/require-jsdoc */
+/**
+ * Copyright IBM Corp. 2016, 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 PrefixContext = /*#__PURE__*/React.createContext('cds');
+function usePrefix() {
+  return React.useContext(PrefixContext);
+}
+
+export { PrefixContext, usePrefix };

package/es/internal/warning.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+export function warning(condition: any, format: any, ...args: any[]): void;

package/es/internal/warning.js

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+
+/* eslint-disable jsdoc/require-jsdoc */
+/**
+ * Copyright IBM Corp. 2016, 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 emptyFunction = function () {};
+
+function warning(condition, format) {
+  for (var _len = arguments.length, args = new Array(_len > 2 ? _len - 2 : 0), _key = 2; _key < _len; _key++) {
+    args[_key - 2] = arguments[_key];
+  }
+  {
+    let index = 0;
+    const message = format.replace(/%s/g, () => {
+      return args[index++];
+    });
+    console.warn('Warning: ' + message);
+  }
+}
+
+export { warning };

package/es/prop-types/AriaPropTypes.d.ts

@@ -0,0 +1 @@
+export const AriaLabelPropType: [key: string];

package/es/prop-types/AriaPropTypes.js

@@ -0,0 +1,16 @@
+/**
+ * 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 PropTypes from 'prop-types';
+import isRequiredOneOf from './isRequiredOneOf.js';
+
+const AriaLabelPropType = isRequiredOneOf({
+  'aria-label': PropTypes.string,
+  'aria-labelledby': PropTypes.string
+});
+
+export { AriaLabelPropType };

package/es/prop-types/deprecate.d.ts

@@ -0,0 +1 @@
+export default function deprecate(propType: any, message: any): (props: any, propName: any, componentName: any, ...rest: any[]) => any;

package/es/prop-types/deprecate.js

@@ -0,0 +1,39 @@
+/**
+ * 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 { warning } from '../internal/warning.js';
+
+/* eslint-disable jsdoc/require-jsdoc */
+/**
+ * Copyright IBM Corp. 2016, 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 didWarnAboutDeprecation = {};
+function deprecate(propType, message) {
+  function checker(props, propName, componentName) {
+    if (props[propName] === undefined) {
+      return;
+    }
+    if (!didWarnAboutDeprecation[componentName] || !didWarnAboutDeprecation[componentName][propName]) {
+      didWarnAboutDeprecation[componentName] = {
+        ...didWarnAboutDeprecation[componentName],
+        [propName]: true
+      };
+      process.env.NODE_ENV !== "production" ? warning(false, message) : void 0;
+    }
+    for (var _len = arguments.length, rest = new Array(_len > 3 ? _len - 3 : 0), _key = 3; _key < _len; _key++) {
+      rest[_key - 3] = arguments[_key];
+    }
+    return propType(props, propName, componentName, ...rest);
+  }
+  return checker;
+}
+
+export { deprecate as default };

package/es/prop-types/isRequiredOneOf.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+/**
+ * @param {[key: string]: Function)} propTypes The list of type checkers, keyed by prop names.
+ * @returns {[key: string]: Function}
+ *   The new prop type checkers that checks if one of the given props exist,
+ *   in addition to the original type checkings.
+ */
+export default function isRequiredOneOf(propTypes: any): [key: string];

package/es/prop-types/isRequiredOneOf.js

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+
+/* eslint-disable jsdoc/valid-types */
+/* eslint-disable jsdoc/require-jsdoc */
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+
+/**
+ * @param {[key: string]: Function)} propTypes The list of type checkers, keyed by prop names.
+ * @returns {[key: string]: Function}
+ *   The new prop type checkers that checks if one of the given props exist,
+ *   in addition to the original type checkings.
+ */
+function isRequiredOneOf(propTypes) {
+  const names = Object.keys(propTypes);
+  const checker = propType => function (props, propName, componentName) {
+    if (process.env.NODE_ENV !== 'production' && names.every(name => typeof props[name] === 'undefined')) {
+      return new Error(`${componentName} requires one of the following props: ${names.join(', ')}`);
+    }
+    for (var _len = arguments.length, rest = new Array(_len > 3 ? _len - 3 : 0), _key = 3; _key < _len; _key++) {
+      rest[_key - 3] = arguments[_key];
+    }
+    return propType(props, propName, componentName, ...rest);
+  };
+  return names.reduce((o, name) => ({
+    ...o,
+    [name]: checker(propTypes[name])
+  }), {});
+}
+
+export { isRequiredOneOf as default };

package/es/types/common.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 * as React from 'react';
+export type ReactAttr<T = HTMLElement> = React.HTMLAttributes<T>;
+export type ForwardRefProps<T, P = unknown> = React.PropsWithoutRef<React.PropsWithChildren<P>> & React.RefAttributes<T>;
+export type ForwardRefReturn<T, P = unknown> = React.ForwardRefExoticComponent<ForwardRefProps<T, P>>;
+/**
+ * For "as" props.  Creates an "as" property that supports native html tags such as 'span', 'a', 'button' as well as custom functional components
+ * All native props for the supplied html tag/component are inferred as part of the base component props, allowing us to use props like `href` on an 'a' element etc
+ */
+export type PolymorphicProps<Element extends React.ElementType, Props> = Props & Omit<React.ComponentProps<Element>, 'as'> & {
+    as?: Element;
+};
+export interface TranslateWithId<MID = string, ARGS = Record<string, unknown>> {
+    /**
+     * Supply a method to translate internal strings with your i18n tool of
+     * choice.
+     */
+    translateWithId?(messageId: MID, args?: ARGS): string;
+}
+/**
+ * Alias of TranslateWithId. Will be removed in v12
+ * @deprecated Use TranslateWithId instead
+ */
+export type InternationalProps<MID = string, ARGS = Record<string, unknown>> = TranslateWithId<MID, ARGS>;

package/lib/components/HeaderPanel.js

@@ -11,11 +11,11 @@ var _rollupPluginBabelHelpers = require('../_virtual/_rollupPluginBabelHelpers.j
 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');
+var usePrefix = require('../internal/usePrefix.js');
+var keys = require('../internal/keyboard/keys.js');
+var match = require('../internal/keyboard/match.js');
+var useEvent = require('../internal/useEvent.js');
+var useMergedRefs = require('../internal/useMergedRefs.js');
 
 const noopFn = () => {};
 const HeaderPanel = /*#__PURE__*/React.forwardRef(function HeaderPanel(_ref, ref) {
@@ -51,7 +51,7 @@ const HeaderPanel = /*#__PURE__*/React.forwardRef(function HeaderPanel(_ref, ref
       }
     };
     eventHandlers.onKeyDown = event => {
-      if (match.match(event, keys.keys.Escape)) {
+      if (match.match(event, keys.Escape)) {
         setExpandedState(false);
         onHeaderPanelFocus();
         if (href) {