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

package/lib/internal/keyboard/match.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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}
+ */
+export function matches(event: Event | React.SyntheticEvent, keysToMatch: Array<Key>): boolean;
+/**
+ * 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}
+ */
+export function match(eventOrCode: React.SyntheticEvent | Event | number | string, { key, which, keyCode, code }?: Key): boolean;
+/**
+ * Get a string character for a given event or event code (useful for synthetic
+ * events)
+ *
+ * @param {Event|number} eventOrCode
+ * @returns {string}
+ */
+export function getCharacterFor(eventOrCode: Event | number): string;
+export type Key = {
+    key: Array<string> | string;
+    which: number;
+    keyCode: number;
+};

package/lib/internal/keyboard/match.js

@@ -0,0 +1,91 @@
+/**
+ * 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';
+
+/* 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;
+}
+
+exports.match = match;
+exports.matches = matches;

package/lib/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/lib/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/lib/internal/useDelayedState.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.
+ */
+
+'use strict';
+
+var React = require('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] = React.useState(initialState);
+  const timeoutId = React.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 = React.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);
+  }, []);
+  React.useEffect(() => {
+    return () => {
+      window.clearTimeout(timeoutId.current ?? undefined);
+    };
+  }, []);
+  return [state, setStateWithDelay];
+}
+
+exports.useDelayedState = useDelayedState;

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

@@ -0,0 +1,57 @@
+/**
+ * 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 React = require('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 = React.useRef(null);
+  React.useEffect(() => {
+    savedCallback.current = callback;
+  }, [callback]);
+  React.useEffect(() => {
+    /**
+     * @type {WindowEventCallback<E>}
+     */
+    function handler(event) {
+      if (savedCallback.current) {
+        savedCallback.current(event);
+      }
+    }
+    window.addEventListener(eventName, handler);
+    return () => {
+      window.removeEventListener(eventName, handler);
+    };
+  }, [eventName]);
+}
+
+exports.useWindowEvent = useWindowEvent;

package/lib/internal/useMatchMedia.d.ts

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

package/lib/internal/useMatchMedia.js

@@ -0,0 +1,54 @@
+/**
+ * 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 React = require('react');
+var environment = require('./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] = React.useState(() => {
+    if (environment.canUseDOM) {
+      const mediaQueryList = window.matchMedia(mediaQueryString);
+      return mediaQueryList.matches;
+    }
+    return false;
+  });
+  React.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;
+}
+
+exports.useMatchMedia = useMatchMedia;

package/lib/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/lib/internal/useMergedRefs.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.
+ */
+
+'use strict';
+
+var React = require('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 React.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);
+};
+
+exports.useMergedRefs = useMergedRefs;

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

@@ -0,0 +1,26 @@
+/**
+ * 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 React = require('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);
+}
+
+exports.PrefixContext = PrefixContext;
+exports.usePrefix = usePrefix;

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

@@ -0,0 +1,33 @@
+/**
+ * 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';
+
+/* 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);
+  }
+}
+
+exports.warning = warning;

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

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

package/lib/prop-types/AriaPropTypes.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';
+
+var PropTypes = require('prop-types');
+var isRequiredOneOf = require('./isRequiredOneOf.js');
+
+const AriaLabelPropType = isRequiredOneOf.default({
+  'aria-label': PropTypes.string,
+  'aria-labelledby': PropTypes.string
+});
+
+exports.AriaLabelPropType = AriaLabelPropType;

package/lib/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/lib/prop-types/deprecate.js

@@ -0,0 +1,43 @@
+/**
+ * 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 warning = require('../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.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;
+}
+
+exports.default = deprecate;

package/lib/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/lib/prop-types/isRequiredOneOf.js

@@ -0,0 +1,44 @@
+/**
+ * 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 });
+
+/* 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])
+  }), {});
+}
+
+exports.default = isRequiredOneOf;