@telus-uds/components-base 3.18.0 → 3.20.0

package/src/utils/useMediaQuerySpacing.js

@@ -0,0 +1,124 @@
+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
+ */
+
+/**
+ * A utility hook that simplifies implementing media query-based responsive spacing.
+ *
+ * This hook handles the complexity of:
+ * - Detecting if a space value is responsive (has viewport keys)
+ * - Fetching theme tokens for each viewport
+ * - Resolving the correct space index for each viewport
+ * - Extracting actual pixel values from theme tokens
+ *
+ * ## Usage
+ *
+ * ```jsx
+ * const { sizeByViewport } = useMediaQuerySpacing(space, 'spacingScale')
+ *
+ * // Use sizeByViewport to create media query styles
+ * const stylesByViewport = {
+ *   xs: { padding: sizeByViewport.xs },
+ *   sm: { padding: sizeByViewport.sm },
+ *   md: { padding: sizeByViewport.md },
+ *   lg: { padding: sizeByViewport.lg },
+ *   xl: { padding: sizeByViewport.xl }
+ * }
+ * const mediaQueryStyles = createMediaQueryStyles(stylesByViewport)
+ * ```
+ *
+ * ## Parameters
+ *
+ * @param {SpacingValue} spaceValue - A spacing value (number or responsive object with viewport keys)
+ * @param {string} tokenKey - The theme token key to use (e.g., 'spacingScale', 'Typography')
+ * @param {object} [tokens={}] - Additional tokens to pass to useThemeTokens
+ * @param {object} [variant={}] - Variant to pass to useThemeTokens
+ *
+ * ## Returns
+ *
+ * @returns {{
+ *   spaceIndexByViewport: { xs: number, sm: number, md: number, lg: number, xl: number },
+ *   sizeByViewport: { xs: number, sm: number, md: number, lg: number, xl: number },
+ *   tokensByViewport: { xs: object, sm: object, md: object, lg: object, xl: object }
+ * }}
+ *
+ * - `spaceIndexByViewport`: The resolved space index for each viewport
+ * - `sizeByViewport`: The actual pixel/number values for each viewport
+ * - `tokensByViewport`: The full theme tokens for each viewport (for advanced use cases)
+ */
+const useMediaQuerySpacing = (spaceValue, tokenKey = 'spacingScale', tokens = {}, variant = {}) => {
+  const isResponsive =
+    typeof spaceValue === 'object' &&
+    spaceValue !== null &&
+    !spaceValue.space &&
+    !spaceValue.options
+
+  const getSpaceIndex = (viewport) => {
+    if (isResponsive) {
+      return resolveResponsiveProp(spaceValue, viewport)
+    }
+    if (typeof spaceValue === 'number') {
+      return spaceValue
+    }
+    return spaceValue?.space ?? 1
+  }
+
+  const spaceIndexByViewport = {
+    xs: getSpaceIndex('xs'),
+    sm: getSpaceIndex('sm'),
+    md: getSpaceIndex('md'),
+    lg: getSpaceIndex('lg'),
+    xl: getSpaceIndex('xl')
+  }
+
+  const tokensXs = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.xs,
+    viewport: 'xs'
+  })
+  const tokensSm = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.sm,
+    viewport: 'sm'
+  })
+  const tokensMd = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.md,
+    viewport: 'md'
+  })
+  const tokensLg = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.lg,
+    viewport: 'lg'
+  })
+  const tokensXl = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.xl,
+    viewport: 'xl'
+  })
+
+  const sizeByViewport = {
+    xs: tokensXs.size ?? 0,
+    sm: tokensSm.size ?? 0,
+    md: tokensMd.size ?? 0,
+    lg: tokensLg.size ?? 0,
+    xl: tokensXl.size ?? 0
+  }
+
+  const tokensByViewport = {
+    xs: tokensXs,
+    sm: tokensSm,
+    md: tokensMd,
+    lg: tokensLg,
+    xl: tokensXl
+  }
+
+  return {
+    spaceIndexByViewport,
+    sizeByViewport,
+    tokensByViewport
+  }
+}
+
+export default useMediaQuerySpacing