@telus-uds/components-base 1.8.1 → 1.8.2

package/lib-module/utils/useCopy.js

@@ -1,42 +0,0 @@
-export const DEFAULT_COPY = 'en';
-/**
- * Extract translations from a keyed dictionary for a given language.
- * Returns a getter.
- *
- * @example
- * const getCopy = useCopy({
- *   copy: 'en',
- *   dictionary: {
- *     en: { label: 'english label' },
- *     fr: { label: 'french label' }
- *   }
- * })
- *
- * getCopy('label') => 'english label'
- *
- * @description The entire dictionary may be overridden by simply passing a single language object as `copy`:
- * @example
- * const getCopy = useCopy({
- *   copy: { label: 'custom label' }
- * })
- *
- * getCopy('label') => 'custom label'
- *
- * @param {object} [dictionary]
- * @param {'en'|'fr'|object} copy - language
- * @return {function(string): string}
- */
-
-function useCopy({
-  dictionary,
-  copy = DEFAULT_COPY
-}) {
-  if (typeof copy === 'string') {
-    return key => key ? dictionary[copy][key] : dictionary[copy];
-  } // support overriding the entire copy dictionary with an object for a single language
-
-
-  return key => copy[key];
-}
-
-export default useCopy;

package/lib-module/utils/useHash.js

@@ -1,44 +0,0 @@
-import { useEffect, useState } from 'react';
-
-const doAction = (action, event) => {
-  var _window, _window$location;
-
-  return typeof action === 'function' && action((_window = window) === null || _window === void 0 ? void 0 : (_window$location = _window.location) === null || _window$location === void 0 ? void 0 : _window$location.hash, event);
-};
-/**
- * @typedef {import('react').SyntheticEvent} SyntheticEvent
- */
-
-/**
- * Calls a function (passing it the current hash) based on the current hash state on mount,
- * and binds it to call it again any time the hash changes.
- *
- * Consider using `useCallback` on the function to minimise adding and removing of event listeners.
- *
- * On Native, this is replaced with a harmless no-op function as there is no direct equivalent.
- *
- * @param {(hash: string, event?: SyntheticEvent) => void} action - a function to act on the current hash on load and when it changes
- * @returns
- */
-
-
-const useHash = (action, isReady = true) => {
-  const [isDone, setIsDone] = useState(false); // Do the action just once when ready after component mount, from hash on page load
-
-  const isToDo = isReady && !isDone;
-  useEffect(() => {
-    if (isToDo) {
-      setIsDone(true);
-      doAction(action);
-    }
-  }, [isToDo, action]); // Bind the action for each hash change; do re-bind if the function changes.
-
-  useEffect(() => {
-    const handleChange = event => doAction(action, event);
-
-    window.addEventListener('hashchange', handleChange);
-    return () => window.removeEventListener('hashchange', handleChange);
-  }, [action]);
-};
-
-export default useHash;

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

@@ -1,7 +0,0 @@
-/**
- * No URL hashes on Native, so do a no-op. Remembering scenes for reloads
- * is handled at OS level and deep links have completely different usage.
- */
-const useHash = () => {};
-
-export default useHash;

package/lib-module/utils/useResponsiveProp.js

@@ -1,47 +0,0 @@
-import { viewports } from '@telus-uds/system-constants';
-import { useViewport } from '../ViewportProvider';
-
-const hasOwn = (objectProp, key) => Object.prototype.hasOwnProperty.call(objectProp, key);
-
-const hasResponsiveProperties = objectProp => viewports.keys.some(key => hasOwn(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 => hasOwn(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/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;

package/lib-module/utils/useUniqueId.js

@@ -1,12 +0,0 @@
-import { useState } from 'react';
-let id = 0;
-
-function useUniqueId(prefix = '') {
-  const [uniqueId] = useState(() => {
-    id += 1;
-    return `${prefix}-${id}`;
-  });
-  return uniqueId;
-}
-
-export default useUniqueId;

package/lib-module/utils/withLinkRouter.js

@@ -1,82 +0,0 @@
-import React, { forwardRef } from 'react';
-import PropTypes from 'prop-types'; // Prototype-safe alternative to (linter-forbidden) someObject.hasOwnProperty()
-
-import { jsx as _jsx } from "react/jsx-runtime";
-
-const hasOwnProperty = (object, prop) => Object.prototype.hasOwnProperty.call(object, prop);
-/**
- * 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} />
- * ```
- */
-
-
-const withLinkRouter = Component => {
-  const wrappedComponent = /*#__PURE__*/forwardRef(({
-    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;