@telus-uds/components-base 2.5.0 → 3.0.0

package/lib/cjs/utils/useResponsiveProp.js

@@ -0,0 +1,53 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveResponsiveProp = exports.default = void 0;
+var _systemConstants = require("@telus-uds/system-constants");
+var _ViewportProvider = require("../ViewportProvider");
+var _hasOwnProperty = _interopRequireDefault(require("./hasOwnProperty"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const hasResponsiveProperties = objectProp => _systemConstants.viewports.keys.some(key => (0, _hasOwnProperty.default)(objectProp, key));
+
+/**
+ * Resolves a prop which may be a responsive object with keys for viewports.
+ *
+ * Used internally in useResponsiveProp - see that for more details.
+ *
+ * @param {*} prop
+ * @param {"xs"|"sm"|"md"|"lg"|"xl"} viewport
+ * @param {*} [defaultValue]
+ * @returns {*}
+ */
+const resolveResponsiveProp = (prop, viewport, defaultValue) => {
+  if (prop === undefined) return defaultValue;
+  if (!prop || typeof prop !== 'object' || !hasResponsiveProperties(prop)) return prop;
+  const value = _systemConstants.viewports.keys.includes(viewport) ?
+  // If there's a current viewport, return the closest match at or below it
+  _systemConstants.viewports.inherit(prop)[viewport] :
+  // If no current viewport is available, default to smallest viewport
+  prop[_systemConstants.viewports.keys.find(key => (0, _hasOwnProperty.default)(prop, key))];
+  return value === undefined ? defaultValue : value;
+};
+
+/**
+ * Takes any value and, if that value is a responsive prop (an object with one or more
+ * keys matching system viewport names), returns the value corresponding to the largest
+ * viewport key smaller than the current screen's viewport.
+ *
+ * For example, if passed `{ sm: 4, lg: 8 }`, it will return 8 on `xl` and `lg` viewports,
+ * 4 on `md` and `sm` viewports, and `undefined` (or a provided `defaultValue`) on `xs` viewports.
+ *
+ * To generate propTypes for responsive props, see `responsiveProps` in `./utils/props/responsiveProps.js`.
+ *
+ * @param {*} prop - any value which may be an object with viewport keys
+ * @param {*} [defaultValue] - default value to provide if no matches found for the current viewport
+ * @returns {*}
+ */
+exports.resolveResponsiveProp = resolveResponsiveProp;
+const useResponsiveProp = (prop, defaultValue) => {
+  const viewport = (0, _ViewportProvider.useViewport)();
+  return resolveResponsiveProp(prop, viewport, defaultValue);
+};
+var _default = exports.default = useResponsiveProp;

package/lib/cjs/utils/useSafeLayoutEffect.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = require("react");
+var _HydrationContext = require("../BaseProvider/HydrationContext");
+const isSSR = typeof window === 'undefined';
+const noop = () => {};
+
+/**
+ * useSafeLayoutEffect is a alternative to useLayoutEffect that avoids SSR hydration problems:
+ *  - In a client-side render, it uses useLayoutEffect to avoid flashing the pre-render UI to the user.
+ *  - During hydration from SSR, the provided function is skipped to avoid mismatches from server content.
+ *  - In SSR, it is a no-op function to avoid warnings about using useLayoutEffect in SSR
+ */
+const useSafeLayoutEffect = isSSR ? noop // avoid React's fussy warnings by ensuring to never call useLayoutEffect on server
+: function (fn) {
+  let deps = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+  const isHydrating = (0, _HydrationContext.useHydrationContext)();
+
+  // Callback updates and effect re-runs when deps array content changes, like useEffect.
+  /* eslint-disable-next-line react-hooks/exhaustive-deps */
+  const callback = (0, _react.useCallback)(fn, deps);
+  (0, _react.useLayoutEffect)(() => {
+    // Do nothing before hydrating server-generated content, like useEffect. When hydration completes,
+    // useHydrationContext provides false, re-rendering this hook and re-running the effect.
+    if (isHydrating) return noop;
+    // If there's no hydration in progress, behave like useLayoutEffect.
+    return callback();
+  }, [isHydrating, callback]);
+};
+var _default = exports.default = useSafeLayoutEffect;

package/lib/cjs/utils/useScrollBlocking.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = require("react");
+const addScrollBlocking = (preventScrolling, stopPropagation, ref) => {
+  document.body.addEventListener('touchmove', preventScrolling, {
+    passive: false
+  });
+  ref.current?.addEventListener('touchmove', stopPropagation);
+  document.body.style.overflow = 'hidden';
+};
+const removeScrollBlocking = (preventScrolling, stopPropagation, ref) => {
+  document.body.removeEventListener('touchmove', preventScrolling);
+  ref.current?.removeEventListener('touchmove', stopPropagation);
+  document.body.style.overflow = 'inherit';
+};
+
+/**
+ * Disables scrolling when passed `true` or an array where all items are `true`.
+ *
+ * Returns an optional callback ref. Pass this to an element if it or its children
+ * should allow touch-based scrolling within that element's bounds.
+ *
+ * @param {boolean | boolean[]} conditionProps
+ * @returns
+ */
+const useScrollBlocking = conditionProps => {
+  // useRef refs are null on first render and don't trigger a re-render when they get their
+  // element. Force re-run when ref mounts to ensure the stopPropagation listener is attached.
+  const ref = (0, _react.useRef)();
+  const [refIsMounted, setRefIsMounted] = (0, _react.useState)(false);
+  const callbackRef = (0, _react.useCallback)(element => {
+    ref.current = element;
+    setRefIsMounted(Boolean(element));
+  }, []);
+  const conditionsMet = Array.isArray(conditionProps) ? conditionProps.every(condition => condition) : Boolean(conditionProps);
+  const preventScrolling = (0, _react.useCallback)(event => event.preventDefault(), []);
+  const stopPropagation = (0, _react.useCallback)(event => event.stopPropagation(), []);
+  (0, _react.useEffect)(() => {
+    const cleanup = () => removeScrollBlocking(preventScrolling, stopPropagation, ref);
+    if (conditionsMet) {
+      addScrollBlocking(preventScrolling, stopPropagation, ref);
+    } else {
+      cleanup();
+    }
+    return cleanup;
+    // preventScrolling and stopPropagation are stable callbacks with no deps, so this
+    // will re-run when conditionsMet or refIsMounted flip between true and false.
+  }, [preventScrolling, conditionsMet, stopPropagation, refIsMounted]);
+  return callbackRef;
+};
+var _default = exports.default = useScrollBlocking;

package/lib/cjs/utils/useScrollBlocking.native.js

@@ -0,0 +1,9 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+// This is a no-op to emphasize that the original hook is web-only
+var _default = () => {};
+exports.default = _default;

package/lib/cjs/utils/useSpacingScale.js

@@ -0,0 +1,129 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ViewportProvider = require("../ViewportProvider");
+var _ThemeProvider = require("../ThemeProvider");
+var _useResponsiveProp = require("./useResponsiveProp");
+/**
+ * @typedef {import('@telus-uds/system-constants/viewports').Viewport} Viewport
+ * @typedef {import('./props/spacingProps.js').SpacingValue} SpacingValue
+ * @typedef {import('./props/spacingProps.js').SpacingIndex} SpacingIndex
+ * @typedef {import('./props/spacingProps.js').SpacingObject} SpacingObject
+ * @typedef {import('./props/spacingProps.js').SpacingOptions} SpacingOptions
+ */
+
+const resolveSpacingOptions = space => {
+  if (!space?.options) return {};
+  const {
+    size,
+    variant,
+    subtract = 0
+  } = space.options;
+  const overridden = typeof size === 'number';
+
+  // Might need an option that adapts the size value by current user's system font scale, so that
+  // meaningful spacing between items doesn't disappear on the highest a11y font scale settings.
+  // https://github.com/telus/universal-design-system/issues/583
+
+  return {
+    tokens: {
+      size
+    },
+    variant,
+    overridden,
+    subtract
+  };
+};
+
+/**
+ * Pass a {@link SpacingValue}, which is one of:
+ *
+ * - A number 0-11 ({@link SpacingIndex}) pointing to an index on the theme's spacing scale
+ * - Or, an object ({@link SpacingObject}), with optional properties:
+ *   -  `xs`, `sm`, `md`, `lg`, `xl`: {@link SpacingIndex} to apply at or above these specified {@link Viewport}
+ *   - `options`: an optional {@link SpacingOptions} object, see below
+ *   - `space`: a {@link SpacingIndex} to apply to all viewports (can be used alongside `options`)
+ *
+ * ## Example
+ *
+ * If the theme's spacing scale is `[0, 4, 8, 12, 16, 24, 48]` with no theme rules:
+ *
+ * - `useSpacingScale(0)` returns `0`
+ * - `useSpacingScale(2)` returns `8`
+ * - `useSpacingScale({ xs: 3, lg: 4 })` returns `12` at 'xs', 'sm' or 'md' viewports, and `16` at 'lg' or 'xl'.
+ *
+ * These viewport properties are intended to support case-specific responsive layout changes, for example, where a
+ * grid item drops or adds spacing on a particular side at viewports where the parent changes the layout shape.
+ *
+ * ## Theming
+ *
+ * A theme's `'spacingScale'` has theme rules and appearances same as components, and may support `viewport`.
+ * For example, a theme with the following rule would change index [2] above from `8` to `12` on large viewports:
+ *
+ * ```json
+ * { if: { space: 2, viewport: ['lg', 'xl'] }, tokens: { size: 12 }}
+ * ```
+ *
+ * Setting responsive spacing in the theme is the preferred way to adapt the aesthetic tightness or looseness of
+ * a theme to the available space without changing the shape of the layout itself.
+ *
+ * ## Options
+ *
+ * Space values passed as objects may have an `options` key, with the following optional properties:
+ *
+ * - `variant`: Themes may choose to have spacing scale variants, same as variants in component themes.
+ *   For example, if a theme rule contains `{ if: { space: 2, compact: true }, tokens: { size: 6 }}`,
+ *   this tighter spacing can be accessed with:
+ *
+ * ```jsx
+ * const compactSize = useSpacingScale({ space: 2, options: { variant: { compact: true }}})`
+ * ```
+ *
+ * - `subtract`: Sometimes on-brand spacing needs to be reduced by another value to achieve an on-brand result.
+ *   For example, a component with a variable border may want to subtract its border width from its padding so
+ *   the total distance from content edge to bounding box is a valid theme value, regardless of border width:
+ *
+ * ```jsx
+ * const padding = useSpacingScale({ space: 2, options: { subtract: themeTokens.borderWidth }})
+ * ```
+ *
+ * - `size`: In exceptional cases, the theme's spacing scale may be bypassed by passing a `size` option.
+ *   This can result in layouts that may be rejected for being off-brand so should only be used as a
+ *   last resort for fixing layout problems (e.g. when working around non-branded embedded content).
+ *   Where possible, fixing layout issues using a spacing scale value and the `subtract` option is preferred.
+ *
+ * ```jsx
+ * // Comments should be included when `size` is used, stating why this off-brand size is needed
+ * const iframeOffset = useSpacingScale({ options: { size: 13 }})`
+ * ```
+ *
+ * ## References
+ *
+ * `/ADRs/inter-component-spacing/README.md` - ADR on this structure
+ *
+ * @param {SpacingValue} [spaceValue] - a {@link SpacingIndex} number, or a {@link SpacingObject}
+ * @returns {number}
+ */
+const useSpacingScale = spaceValue => {
+  // In future, may need to consider window height as well as width, particularly for native apps,
+  // e.g. to ensure designs don't look lost on large, tall, not-so-wide portrait screens.
+  const viewport = (0, _ViewportProvider.useViewport)();
+  const {
+    tokens,
+    variant,
+    overridden,
+    subtract = 0
+  } = resolveSpacingOptions(spaceValue);
+  const space = !overridden && (spaceValue?.space ?? (0, _useResponsiveProp.resolveResponsiveProp)(spaceValue, viewport, 0));
+  const {
+    size
+  } = (0, _ThemeProvider.useThemeTokens)('spacingScale', tokens, variant, {
+    space: typeof space === 'number' ? space : 0,
+    viewport
+  });
+  return Math.max(size - subtract, 0);
+};
+var _default = exports.default = useSpacingScale;

package/lib/cjs/utils/useUniqueId.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = require("react");
+let id = 0;
+function useUniqueId() {
+  let prefix = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '';
+  const [uniqueId] = (0, _react.useState)(() => {
+    id += 1;
+    return `${prefix}-${id}`;
+  });
+  return uniqueId;
+}
+var _default = exports.default = useUniqueId;

package/lib/cjs/utils/withLinkRouter.js

@@ -0,0 +1,89 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var _hasOwnProperty = _interopRequireDefault(require("./hasOwnProperty"));
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Higher-order component that has no effect unless an additional prop `LinkRouter` is passed.
+ * This may be used to provide custom wrappers for integrations with third party libraries.
+ *
+ * If LinkRouter is passed, LinkRouter is rendered in place of the main component and is passed:
+ *
+ *  - `linkRouterProps`: an optional object passed alongside LinkRouter, for props needed by the wrapper
+ *    that are not valid props for the wrapped component.
+ *  - `Component`: automatically provided, the original component to render inside the wrapper.
+ *  - `ref`: forwarded `ref` passed down to `Component`
+ *  - All other props passed to the outer component
+ *
+ * @example A LinkRouter component to be used with link-like components might look like:
+ *
+ * ```jsx
+ * const LinkLinkRouter = React.forwardRef(({ Component, linkRouterProps: { to, options }, href, ...rest }, ref) => {
+ *   const { href: resolvedHref, onClick } = useSomeRouterHook({ to, href, options })
+ *   return <Component href={resolvedHref} onPress={onClick} {...rest} />
+ * })
+ * ```
+ *
+ * Any component that takes href and onPress props may then use this wrapper:
+ *
+ * ```jsx
+ * <Link href={href} LinkRouter={LinkLinkRouter} linkRouterProps={{ to, options }}>Some link</Link>
+ * <IconButton icon={SomeIcon} LinkRouter={LinkLinkRouter} linkRouterProps={{ to, options }} ref={iconRef} />
+ * ```
+ */const withLinkRouter = Component => {
+  const wrappedComponent = /*#__PURE__*/_react.default.forwardRef((_ref, ref) => {
+    let {
+      LinkRouter,
+      linkRouterProps,
+      ...props
+    } = _ref;
+    if (!LinkRouter) return /*#__PURE__*/(0, _jsxRuntime.jsx)(Component, {
+      ...props,
+      ref: ref
+    });
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(LinkRouter, {
+      linkRouterProps: linkRouterProps,
+      Component: Component,
+      ref: ref,
+      ...props
+    });
+  });
+
+  // Ensure the returned component has appropriate outer properties set:
+  /* eslint-disable-next-line react/forbid-foreign-prop-types */
+  const {
+    displayName,
+    name,
+    propTypes,
+    ...otherProperties
+  } = Component;
+
+  // Apply unique component name as a displayName
+  wrappedComponent.displayName = Component.displayName || Component.name;
+
+  // Apply proptypes including wrapper props - is safely { ...undefined, ...undefined } in prod
+  wrappedComponent.propTypes = {
+    ...Component.propTypes,
+    ...withLinkRouter.propTypes
+  };
+
+  // Forward any other properties explicitly set e.g. Component.SubComponent
+  Object.keys(otherProperties).forEach(key => {
+    // Skip internal React properties from wrappedComponent's forwardRef (render, $$typeof, etc)
+    if ((0, _hasOwnProperty.default)(Component, key) && !(0, _hasOwnProperty.default)(wrappedComponent, key)) {
+      wrappedComponent[key] = Component[key];
+    }
+  });
+  return wrappedComponent;
+};
+withLinkRouter.propTypes = {
+  LinkRouter: _propTypes.default.elementType,
+  linkRouterProps: _propTypes.default.object
+};
+var _default = exports.default = withLinkRouter;