@telus-uds/components-base 2.0.0 → 2.0.1

package/lib-module/utils/useResponsiveProp.js

@@ -1,46 +0,0 @@
-import { viewports } from '@telus-uds/system-constants';
-import { useViewport } from '../ViewportProvider';
-import hasOwnProperty from './hasOwnProperty';
-
-const hasResponsiveProperties = objectProp => viewports.keys.some(key => hasOwnProperty(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 {*}
- */
-
-
-export const resolveResponsiveProp = (prop, viewport, defaultValue) => {
-  if (prop === undefined) return defaultValue;
-  if (!prop || typeof prop !== 'object' || !hasResponsiveProperties(prop)) return prop;
-  const value = viewports.keys.includes(viewport) ? // If there's a current viewport, return the closest match at or below it
-  viewports.inherit(prop)[viewport] : // If no current viewport is available, default to smallest viewport
-  prop[viewports.keys.find(key => hasOwnProperty(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 {*}
- */
-
-const useResponsiveProp = (prop, defaultValue) => {
-  const viewport = useViewport();
-  return resolveResponsiveProp(prop, viewport, defaultValue);
-};
-
-export default useResponsiveProp;

package/lib-module/utils/useSafeLayoutEffect.js

@@ -1,30 +0,0 @@
-import { useLayoutEffect, useCallback } from 'react';
-import { useHydrationContext } from '../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 = useHydrationContext(); // Callback updates and effect re-runs when deps array content changes, like useEffect.
-
-  /* eslint-disable-next-line react-hooks/exhaustive-deps */
-
-  const callback = useCallback(fn, deps);
-  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]);
-};
-export default useSafeLayoutEffect;

package/lib-module/utils/useScrollBlocking.js

@@ -1,58 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-
-const addScrollBlocking = (preventScrolling, stopPropagation, ref) => {
-  var _ref$current;
-
-  document.body.addEventListener('touchmove', preventScrolling, {
-    passive: false
-  });
-  (_ref$current = ref.current) === null || _ref$current === void 0 ? void 0 : _ref$current.addEventListener('touchmove', stopPropagation);
-  document.body.style.overflow = 'hidden';
-};
-
-const removeScrollBlocking = (preventScrolling, stopPropagation, ref) => {
-  var _ref$current2;
-
-  document.body.removeEventListener('touchmove', preventScrolling);
-  (_ref$current2 = ref.current) === null || _ref$current2 === void 0 ? void 0 : _ref$current2.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 = useRef();
-  const [refIsMounted, setRefIsMounted] = useState(false);
-  const callbackRef = useCallback(element => {
-    ref.current = element;
-    setRefIsMounted(Boolean(element));
-  }, []);
-  const conditionsMet = Array.isArray(conditionProps) ? conditionProps.every(condition => condition) : Boolean(conditionProps);
-  const preventScrolling = useCallback(event => event.preventDefault(), []);
-  const stopPropagation = useCallback(event => event.stopPropagation(), []);
-  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;
-};
-
-export default useScrollBlocking;

package/lib-module/utils/useScrollBlocking.native.js

@@ -1,2 +0,0 @@
-// This is a no-op to emphasize that the original hook is web-only
-export default (() => {});

package/lib-module/utils/useSpacingScale.js

@@ -1,125 +0,0 @@
-import { useViewport } from '../ViewportProvider';
-import { useThemeTokens } from '../ThemeProvider';
-import { resolveResponsiveProp } from './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 !== null && space !== void 0 && 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 => {
-  var _spaceValue$space;
-
-  // 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 = useViewport();
-  const {
-    tokens,
-    variant,
-    overridden,
-    subtract = 0
-  } = resolveSpacingOptions(spaceValue);
-  const space = !overridden && ((_spaceValue$space = spaceValue === null || spaceValue === void 0 ? void 0 : spaceValue.space) !== null && _spaceValue$space !== void 0 ? _spaceValue$space : resolveResponsiveProp(spaceValue, viewport, 0));
-  const {
-    size
-  } = useThemeTokens('spacingScale', tokens, variant, {
-    space: typeof space === 'number' ? space : 0,
-    viewport
-  });
-  return Math.max(size - subtract, 0);
-};
-
-export default useSpacingScale;

package/lib-module/utils/useUniqueId.js

@@ -1,13 +0,0 @@
-import { useState } from 'react';
-let id = 0;
-
-function useUniqueId() {
-  let prefix = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '';
-  const [uniqueId] = useState(() => {
-    id += 1;
-    return "".concat(prefix, "-").concat(id);
-  });
-  return uniqueId;
-}
-
-export default useUniqueId;

package/lib-module/utils/withLinkRouter.js

@@ -1,81 +0,0 @@
-import React, { forwardRef } from 'react';
-import PropTypes from 'prop-types';
-import hasOwnProperty from './hasOwnProperty';
-/**
- * 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 = 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} />
- * ```
- */
-
-import { jsx as _jsx } from "react/jsx-runtime";
-
-const withLinkRouter = Component => {
-  const wrappedComponent = /*#__PURE__*/forwardRef((_ref, ref) => {
-    let {
-      LinkRouter,
-      linkRouterProps,
-      ...props
-    } = _ref;
-    if (!LinkRouter) return /*#__PURE__*/_jsx(Component, { ...props,
-      ref: ref
-    });
-    return /*#__PURE__*/_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 (hasOwnProperty(Component, key) && !hasOwnProperty(wrappedComponent, key)) {
-      wrappedComponent[key] = Component[key];
-    }
-  });
-  return wrappedComponent;
-};
-
-withLinkRouter.propTypes = {
-  LinkRouter: PropTypes.elementType,
-  linkRouterProps: PropTypes.object
-};
-export default withLinkRouter;