@telus-uds/components-base 2.4.0 → 3.0.0

package/lib/utils/useOverlaidPosition.js

@@ -1,214 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-import Dimensions from "react-native-web/dist/exports/Dimensions";
-import Platform from "react-native-web/dist/exports/Platform";
-const adjustHorizontalToFit = (initialOffset, windowWidth, sourceWidth) => {
-  const offset = Math.max(0, initialOffset);
-  const otherEdgeOverflow = Math.max(0, offset + sourceWidth - windowWidth);
-  const tooWideBy = Math.max(0, otherEdgeOverflow - offset);
-  const adjusted = {
-    offset: Math.max(0, offset - otherEdgeOverflow)
-  };
-  if (tooWideBy) adjusted.width = Math.max(0, sourceWidth - tooWideBy);
-  return adjusted;
-};
-const getPosition = _ref => {
-  let {
-    edge,
-    fromEdge,
-    sourceSize
-  } = _ref;
-  switch (edge) {
-    case 'near':
-      return fromEdge;
-    case 'mid':
-      return fromEdge + sourceSize / 2;
-    case 'far':
-      return fromEdge + sourceSize;
-    default:
-      return 0;
-  }
-};
-const getEdgeType = (align, alignSide) => {
-  const alignTo = align[alignSide];
-  const edge = ['center', 'middle'].includes(alignTo) && 'mid' || (alignSide === alignTo ? 'near' : 'far');
-  return edge;
-};
-
-/**
- * Based on UDS's private getTooltipPosition but generalised.
- *
- * Used for absolute positioning of the tooltip. Since the tooltip is always centered relatively
- * to the source (button) and we have a limited set of positions, an easy and consistent way
- * of positioning it is to check all of the possible positions and pick one that will be rendered
- * within the window bounds. This way we can also rely on the tooltip being actually rendered
- * before it is shown, which makes it account for the width being limiting in styles, custom font
- * rendering, etc.
- */
-function getOverlaidPosition(_ref2) {
-  let {
-    sourceLayout,
-    targetDimensions,
-    windowDimensions,
-    offsets = {},
-    align
-  } = _ref2;
-  // Web-only: this will be difficult to mimic on native because there's no global scroll position.
-  // TODO: wire something in e.g. a scroll ref accessible from a provider included in Allium provider
-  // that can be passed to the appropriate ScrollView?
-  const {
-    scrollX = 0,
-    scrollY = 0
-  } = typeof window === 'object' ? window : {};
-
-  // Will have top, bottom, left and/or right offsets depending on `align`
-  const positioning = {};
-  if (align.top) positioning.top = getPosition({
-    edge: getEdgeType(align, 'top'),
-    fromEdge: sourceLayout.y + scrollY + (offsets.vertical ?? 0),
-    sourceSize: sourceLayout.height
-  });
-  if (align.middle) positioning.top = getPosition({
-    edge: getEdgeType(align, 'middle'),
-    fromEdge: sourceLayout.y + scrollY + (offsets.vertical ?? 0) - targetDimensions.height / 2,
-    sourceSize: sourceLayout.height
-  });
-  if (align.bottom) positioning.bottom = getPosition({
-    edge: getEdgeType(align, 'bottom'),
-    fromEdge: windowDimensions.height - (sourceLayout.y + scrollY + sourceLayout.height - (offsets.vertical ?? 0)),
-    sourceSize: sourceLayout.height
-  });
-  if (align.left) positioning.left = getPosition({
-    edge: getEdgeType(align, 'left'),
-    fromEdge: sourceLayout.x + scrollX + (offsets.horizontal ?? 0),
-    sourceSize: sourceLayout.width
-  });
-  if (align.center) positioning.left = getPosition({
-    edge: getEdgeType(align, 'center'),
-    fromEdge: sourceLayout.x + scrollX + (offsets.horizontal ?? 0) - targetDimensions.width / 2,
-    sourceSize: sourceLayout.width
-  });
-  if (align.right) positioning.right = getPosition({
-    edge: getEdgeType(align, 'right'),
-    fromEdge: windowDimensions.width - (sourceLayout.x + scrollX + sourceLayout.width - (offsets.horizontal ?? 0)),
-    sourceSize: sourceLayout.width
-  });
-  if (!(align.left && align.right)) {
-    // Check if the position and/or width need adjusting to fit on the screen
-    const side = align.right ? 'right' : 'left';
-    const adjusted = adjustHorizontalToFit(positioning[side], windowDimensions.width, sourceLayout.width);
-    if (typeof adjusted.width === 'number') positioning.width = adjusted.width;
-    if (typeof adjusted.offset === 'number') {
-      positioning[side] = adjusted.offset;
-    }
-  }
-  return positioning;
-}
-
-/**
- * Positions an element in a modal or portal so that it appears tooltip-like below the
- * target element.
- *
- * @TODO - add support for positioning other than 'below' like UDS's tooltip (this is not
- * a small task because UDS's tooltip logic only really works for short text - it might be
- * better to use a third-party library).
- */
-const useOverlaidPosition = _ref3 => {
-  let {
-    isShown = false,
-    offsets,
-    // By default, align the overlaid target's `top` to the bottom of the source, and center horizontally.
-    align = {
-      center: 'center',
-      top: 'bottom'
-    }
-  } = _ref3;
-  // Element in main document flow that the targetRef element is positioned around
-  const sourceRef = useRef(null);
-  const [sourceLayout, setSourceLayout] = useState(null);
-
-  // Element in a modal or portal overlay positioned to appear adjacent to sourceRef
-  const targetRef = useRef(null);
-  const [targetDimensions, setTargetDimensions] = useState(null);
-  const [windowDimensions, setWindowDimensions] = useState(null);
-  const onTargetLayout = useCallback(_ref4 => {
-    let {
-      nativeEvent: {
-        layout: {
-          width,
-          height
-        }
-      }
-    } = _ref4;
-    // NOTE: UDS's Tooltip logic injects some additional width to allow for antialiasing etc of text,
-    // avoiding adding unnecessary line breaks to text that is slightly wider than it thinks it is.
-    // That is probably something specific to text tooltips that doesn't belong in a generic hook.
-    setTargetDimensions(previousDimensions => {
-      // Re-render on first non-zero width / height: avoid infinite loops on changes, or mispositioning
-      // if user scrolls while a slidedown animation is changing the height and recalculating position.
-      if (!previousDimensions && width && height) {
-        return {
-          width,
-          height
-        };
-      }
-      return previousDimensions;
-    });
-  }, []);
-  const readyToShow = Boolean(isShown && sourceRef.current);
-  useEffect(() => {
-    const handleDimensionsChange = _ref5 => {
-      var _sourceRef$current;
-      let {
-        window
-      } = _ref5;
-      const measurementFunction = Platform.OS === 'web' ? 'measureInWindow' : 'measure';
-      (_sourceRef$current = sourceRef.current) === null || _sourceRef$current === void 0 || _sourceRef$current[measurementFunction]((x, y, width, height) => {
-        setWindowDimensions(window);
-        setSourceLayout({
-          x,
-          y,
-          width,
-          height
-        });
-      });
-    };
-    let subscription;
-    const unsubscribe = () => {
-      var _subscription;
-      if (typeof ((_subscription = subscription) === null || _subscription === void 0 ? void 0 : _subscription.remove) === 'function') {
-        // React Native >=0.65.0
-        subscription.remove();
-      } else if (typeof Dimensions.remove === 'function') {
-        // React Native <0.65.0
-        Dimensions.remove('change', handleDimensionsChange);
-      }
-      setSourceLayout(null);
-      setTargetDimensions(null);
-    };
-    if (readyToShow) {
-      subscription = Dimensions.addEventListener('change', handleDimensionsChange);
-      handleDimensionsChange({
-        window: Dimensions.get('window')
-      });
-    } else {
-      unsubscribe();
-    }
-    return unsubscribe;
-  }, [readyToShow]);
-  const isReady = Boolean(isShown && sourceLayout && windowDimensions && targetDimensions);
-  const overlaidPosition = isReady ? getOverlaidPosition({
-    sourceLayout,
-    targetDimensions,
-    windowDimensions,
-    offsets,
-    align
-  }) : {};
-  return {
-    overlaidPosition,
-    sourceRef,
-    targetRef,
-    onTargetLayout,
-    isReady
-  };
-};
-export default useOverlaidPosition;

package/lib/utils/useScrollBlocking.js

@@ -1,51 +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 || _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 || _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/utils/useSpacingScale.js

@@ -1,123 +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 => {
-  // 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 === null || spaceValue === void 0 ? 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;