@telus-uds/components-base 2.4.0 → 3.0.0

package/lib/esm/utils/useOverlaidPosition.js

@@ -0,0 +1,235 @@
+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";
+import debounce from 'lodash.debounce';
+const DEBOUNCE_DELAY = 100;
+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 => {
+      let {
+        window
+      } = _ref5;
+      const measurementFunction = Platform.OS === 'web' ? 'measureInWindow' : 'measure';
+      sourceRef.current?.[measurementFunction]((x, y, width, height) => {
+        setWindowDimensions(window);
+        setSourceLayout({
+          x,
+          y,
+          width,
+          height
+        });
+      });
+    };
+    let subscription;
+    const unsubscribe = () => {
+      if (typeof 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]);
+  useEffect(() => {
+    if (Platform.OS !== 'web') {
+      return undefined;
+    }
+    const handleScroll = debounce(() => {
+      sourceRef.current?.measureInWindow((x, y, width, height) => {
+        setWindowDimensions(window);
+        setSourceLayout({
+          x,
+          y,
+          width,
+          height
+        });
+      });
+    }, DEBOUNCE_DELAY);
+    window.addEventListener('scroll', handleScroll);
+    return () => {
+      window.removeEventListener('scroll', handleScroll);
+      handleScroll.cancel();
+    };
+  }, [sourceRef]);
+  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/esm/utils/useScrollBlocking.js

@@ -0,0 +1,49 @@
+import { useCallback, useEffect, useRef, useState } from '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 = 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/esm/utils/useSpacingScale.js

@@ -0,0 +1,123 @@
+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?.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?.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/package.json

@@ -0,0 +1,88 @@
+{
+  "author": "TELUS Digital",
+  "browserslist": [
+    "extends @telus-uds/browserslist-config"
+  ],
+  "bugs": {
+    "url": "https://github.com/telus/universal-design-system/issues"
+  },
+  "dependencies": {
+    "@floating-ui/react-dom": "^1.0.1",
+    "@floating-ui/react-native": "^0.8.1",
+    "@gorhom/portal": "^1.0.14",
+    "@react-native-picker/picker": "^2.9.0",
+    "@telus-uds/system-constants": "^3.0.0",
+    "@telus-uds/system-theme-tokens": "^4.0.0",
+    "airbnb-prop-types": "^2.16.0",
+    "css-mediaquery": "^0.1.2",
+    "expo-document-picker": "^13.0.1",
+    "expo-linear-gradient": "^12.5.0",
+    "expo-modules-core": "^1.12.24",
+    "lodash.debounce": "^4.0.8",
+    "lodash.merge": "^4.6.2",
+    "lodash.throttle": "^4.1.1",
+    "prop-types": "^15.7.2",
+    "react-native-picker-select": "^9.3.1",
+    "semver": "7.5.2",
+    "string.prototype.matchall": "^4.0.9"
+  },
+  "description": "Base components",
+  "devDependencies": {
+    "@babel/plugin-transform-private-methods": "^7.25.4",
+    "@telus-uds/browserslist-config": "^1.0.5",
+    "@testing-library/jest-native": "^4.0.1",
+    "@testing-library/react": "^13.3.0",
+    "@testing-library/react-hooks": "~7.0.1",
+    "@testing-library/react-native": "11.0.0",
+    "react-test-renderer": "~18.0.0",
+    "webpack": "5.x"
+  },
+  "exports": {
+    ".": {
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js"
+    },
+    "./server": {
+      "import": "./lib/esm/server.js",
+      "require": "./lib/cjs/server.js"
+    }
+  },
+  "homepage": "https://github.com/telus/universal-design-system#readme",
+  "keywords": [
+    "base"
+  ],
+  "license": "MIT",
+  "main": "lib/cjs/index.js",
+  "module": "lib/esm/index.js",
+  "name": "@telus-uds/components-base",
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-native": "^0.74.5",
+    "react-native-web": "^0.19.10"
+  },
+  "react-native": "src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telus/universal-design-system.git"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:web": "jest --config jest.config-web.js",
+    "test:ios": "jest --config jest.config-ios.js",
+    "test:android": "jest --config jest.config-android.js",
+    "lint": "npm run --prefix ../.. lint:path -- --color packages/components-base",
+    "lint:fix": "npm run --prefix ../.. lint:path -- --fix packages/components-base",
+    "format": "prettier --write .",
+    "build:cjs": "babel src -d lib/cjs",
+    "copy:pkg": "cp package.json lib/package.json",
+    "build:esm": "babel src -d lib/esm --env-name module",
+    "build": "npm run build:cjs && npm run build:esm && npm run copy:pkg"
+  },
+  "sideEffects": false,
+  "standard-engine": {
+    "skip": true
+  },
+  "version": "3.0.0",
+  "types": "types/index.d.ts"
+}

package/package.json

@@ -3,7 +3,6 @@
   "browserslist": [
     "extends @telus-uds/browserslist-config"
   ],
-  "type": "module",
   "bugs": {
     "url": "https://github.com/telus/universal-design-system/issues"
   },
@@ -12,8 +11,8 @@
     "@floating-ui/react-native": "^0.8.1",
     "@gorhom/portal": "^1.0.14",
     "@react-native-picker/picker": "^2.9.0",
-    "@telus-uds/system-constants": "^2.0.0",
-    "@telus-uds/system-theme-tokens": "^3.3.0",
+    "@telus-uds/system-constants": "^3.0.0",
+    "@telus-uds/system-theme-tokens": "^4.0.0",
     "airbnb-prop-types": "^2.16.0",
     "css-mediaquery": "^0.1.2",
     "expo-document-picker": "^13.0.1",
@@ -40,12 +39,12 @@
   },
   "exports": {
     ".": {
-      "import": "./lib/index.js",
-      "default": "./lib/index.js"
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js"
     },
     "./server": {
-      "import": "./lib/server.js",
-      "default": "./lib/server.js"
+      "import": "./lib/esm/server.js",
+      "require": "./lib/cjs/server.js"
     }
   },
   "homepage": "https://github.com/telus/universal-design-system#readme",
@@ -53,8 +52,8 @@
     "base"
   ],
   "license": "MIT",
-  "main": "lib/index.js",
-  "module": "lib/index.js",
+  "main": "lib/cjs/index.js",
+  "module": "lib/esm/index.js",
   "name": "@telus-uds/components-base",
   "peerDependencies": {
     "react": "^18.2.0",
@@ -75,12 +74,15 @@
     "lint": "npm run --prefix ../.. lint:path -- --color packages/components-base",
     "lint:fix": "npm run --prefix ../.. lint:path -- --fix packages/components-base",
     "format": "prettier --write .",
-    "build": "babel src -d lib --env-name module"
+    "build:cjs": "babel src -d lib/cjs",
+    "copy:pkg": "cp package.json lib/package.json",
+    "build:esm": "babel src -d lib/esm --env-name module",
+    "build": "npm run build:cjs && npm run build:esm && npm run copy:pkg"
   },
   "sideEffects": false,
   "standard-engine": {
     "skip": true
   },
-  "version": "2.4.0",
+  "version": "3.0.0",
   "types": "types/index.d.ts"
 }