@telus-uds/components-base 1.17.0 → 1.18.1

package/CHANGELOG.md

@@ -1,12 +1,32 @@
 # Change Log - @telus-uds/components-base
 
-This log was last generated on Mon, 19 Sep 2022 22:48:56 GMT and should not be manually modified.
+This log was last generated on Wed, 05 Oct 2022 21:29:58 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 1.18.1
+
+Wed, 05 Oct 2022 21:29:58 GMT
+
+### Patches
+
+- feat: add passing native / test ID from the search to the input (ruslan.bredikhin@nearform.com)
+
+## 1.18.0
+
+Tue, 27 Sep 2022 19:33:40 GMT
+
+### Minor changes
+
+- Add exported useSafeLayoutEffect utility (alan.slater@nearform.com)
+
+### Patches
+
+- Fix SSR hydration mismatches (alan.slater@nearform.com)
+
 ## 1.17.0
 
-Mon, 19 Sep 2022 22:48:56 GMT
+Mon, 19 Sep 2022 22:51:24 GMT
 
 ### Minor changes
 

package/lib/BaseProvider/HydrationContext.js

@@ -0,0 +1,74 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useHydrationContext = exports.default = exports.HydrationProvider = void 0;
+
+var _react = _interopRequireWildcard(require("react"));
+
+var _propTypes = _interopRequireDefault(require("prop-types"));
+
+var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
+
+var _jsxRuntime = require("react/jsx-runtime");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function (nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
+
+function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
+
+const HydrationContext = /*#__PURE__*/(0, _react.createContext)();
+const isSSR = typeof window === 'undefined';
+
+const hasWebStyleTag = () => {
+  var _document;
+
+  if (isSSR || _Platform.default.OS !== 'web' || typeof document !== 'object') {
+    return false;
+  }
+
+  return Boolean((_document = document) === null || _document === void 0 ? void 0 : _document.getElementById('react-native-stylesheet'));
+};
+/**
+ * Returns true if this render cycle is the hydration of existing SSR content.
+ *
+ * Use this when changing how content renders based on data that is instantly available
+ * during the very first client-side render or hydration, but not available on the server,
+ * to ensure no changes happen until the original SSR DOM has been hydrated.
+ */
+
+
+const useHydrationContext = () => (0, _react.useContext)(HydrationContext);
+/**
+ * Allows components and hooks to observe if SSR hydration is currently in progress
+ * and if so, to re-render with content that differs to the server when it is complete.
+ */
+
+
+exports.useHydrationContext = useHydrationContext;
+
+const HydrationProvider = _ref => {
+  let {
+    children
+  } = _ref;
+  const [hasMounted, setHasMounted] = (0, _react.useState)(false);
+  (0, _react.useEffect)(() => {
+    setHasMounted(true);
+  }, []); // If we've got a HydrationProvider inside a HydrationProvider somehow, defer to the top one
+
+  const valueFromAncestor = useHydrationContext();
+  const isHydrating = valueFromAncestor !== null && valueFromAncestor !== void 0 ? valueFromAncestor : Boolean(!hasMounted && hasWebStyleTag());
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(HydrationContext.Provider, {
+    value: isHydrating,
+    children: children
+  });
+};
+
+exports.HydrationProvider = HydrationProvider;
+HydrationProvider.propTypes = {
+  children: _propTypes.default.node
+};
+var _default = HydrationProvider;
+exports.default = _default;

package/lib/BaseProvider/index.js

@@ -17,6 +17,8 @@ var _ViewportProvider = _interopRequireDefault(require("../ViewportProvider"));
 
 var _ThemeProvider = _interopRequireDefault(require("../ThemeProvider"));
 
+var _HydrationContext = require("./HydrationContext");
+
 var _jsxRuntime = require("react/jsx-runtime");
 
 var _ThemeProvider$propTy;
@@ -29,13 +31,15 @@ const BaseProvider = _ref => {
     children,
     themeOptions
   } = _ref;
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_A11yInfoProvider.default, {
-    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_ViewportProvider.default, {
-      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_ThemeProvider.default, {
-        defaultTheme: defaultTheme,
-        themeOptions: themeOptions,
-        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_portal.PortalProvider, {
-          children: children
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_HydrationContext.HydrationProvider, {
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_A11yInfoProvider.default, {
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_ViewportProvider.default, {
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_ThemeProvider.default, {
+          defaultTheme: defaultTheme,
+          themeOptions: themeOptions,
+          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_portal.PortalProvider, {
+            children: children
+          })
         })
       })
     })

package/lib/Search/Search.js

@@ -159,10 +159,18 @@ const Search = /*#__PURE__*/(0, _react.forwardRef)((_ref4, ref) => {
   const a11yLabelText = accessibilityLabel || getCopy('accessibilityLabel'); // Placeholder is optional and may be unset by passing an empty string
 
   const placeholderText = placeholder !== null && placeholder !== void 0 ? placeholder : a11yLabelText;
+  const {
+    nativeID,
+    testID,
+    ...containerProps
+  } = selectContainerProps(rest);
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_View.default, {
     style: staticStyles.container,
-    ...selectContainerProps(rest),
-    children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_TextInputBase.default, { ...selectInputProps(rest),
+    ...containerProps,
+    children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_TextInputBase.default, {
+      nativeID: nativeID,
+      testID: testID,
+      ...selectInputProps(rest),
       ref: ref,
       tokens: appearances => selectInputTokens({
         searchTokens: getThemeTokens(appearances),

package/lib/StackView/StackWrap.js

@@ -9,6 +9,8 @@ var _react = _interopRequireWildcard(require("react"));
 
 var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
 
+var _useSafeLayoutEffect = _interopRequireDefault(require("../utils/useSafeLayoutEffect"));
+
 var _StackWrapBox = _interopRequireDefault(require("./StackWrapBox"));
 
 var _StackWrapGap = _interopRequireDefault(require("./StackWrapGap"));
@@ -22,10 +24,10 @@ function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "functio
 function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
 
 // In Jest/CI/SSR, global CSS isn't always available and doesn't always have .supports method
-const cssSupports = function () {
+const cssSupports = (property, value) => {
   var _window$CSS;
 
-  return typeof window !== 'undefined' && typeof ((_window$CSS = window.CSS) === null || _window$CSS === void 0 ? void 0 : _window$CSS.supports) === 'function' && window.CSS.supports(...arguments);
+  return _Platform.default.OS === 'web' && typeof window !== 'undefined' && typeof ((_window$CSS = window.CSS) === null || _window$CSS === void 0 ? void 0 : _window$CSS.supports) === 'function' && window.CSS.supports(property, value);
 }; // CSS.supports needs an example of the type of value you intend to use.
 // Will be an integer appended `px` after hooks and JSX styles are resolved.
 
@@ -42,22 +44,24 @@ const exampleGapValue = '1px';
 const StackWrap = /*#__PURE__*/(0, _react.forwardRef)((props, ref) => {
   var _props$gap;
 
+  const [canUseCSSGap, setCanUseCSSGap] = (0, _react.useState)(false);
   const {
     space
   } = props; // Don't apply separate gap if `null` or `undefined`, so can be unset in Storybook etc
 
   const gap = (_props$gap = props.gap) !== null && _props$gap !== void 0 ? _props$gap : space;
-  const canUseCSSGap = _Platform.default.OS === 'web' && gap === space && cssSupports('gap', exampleGapValue);
-  return canUseCSSGap ?
-  /*#__PURE__*/
-  // If possible, use the cleaner implementation that applies CSS `gap` styles to the container.
-  (0, _jsxRuntime.jsx)(_StackWrapGap.default, {
-    ref: ref,
-    ...props
-  }) :
-  /*#__PURE__*/
+  const gapEqualsSpace = gap === space; // If possible, use the cleaner implementation that applies CSS `gap` styles to the container,
+  // preserving direct parent-child relationships between the container and each item, which
+  // can result in clearer descriptions on some screen readers (e.g. radio "X of Y" on MacOS).
   // Else, use the fallback implementation which renders a `Box` component around each child.
-  (0, _jsxRuntime.jsx)(_StackWrapBox.default, {
+
+  const Component = canUseCSSGap ? _StackWrapGap.default : _StackWrapBox.default; // In SSR, the type of implementation must match the server during hydration, but
+  // the server can't know if gap is supported, so never use it until after hydration.
+
+  (0, _useSafeLayoutEffect.default)(() => {
+    setCanUseCSSGap(gapEqualsSpace && cssSupports('gap', exampleGapValue));
+  }, [gapEqualsSpace]);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(Component, {
     ref: ref,
     ...props
   });

package/lib/ViewportProvider/useViewportListener.js

@@ -5,28 +5,18 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 
-var _react = require("react");
-
 var _Dimensions = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Dimensions"));
 
 var _systemConstants = require("@telus-uds/system-constants");
 
+var _useSafeLayoutEffect = _interopRequireDefault(require("../utils/useSafeLayoutEffect"));
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
 // Use Dimensions instead of useWindowDimensions because useWindowDimensions forces context
 // to update on every pixel change during window resize; but we only want rerenders to occur
 // when a viewport threshold has been crossed.
 const lookupViewport = () => _systemConstants.viewports.select(_Dimensions.default.get('window').width);
-/**
- * In SSR, React gets spooked if it sees `useLayoutEffect` and fires warnings assuming the
- * developer doesn't realise the effect won't run: https://reactjs.org/link/uselayouteffect-ssr
- *
- * To avoid these warnings while still conforming to the rules of hooks, always use this
- * explicitly no-op hook, instead of the useLayoutEffect that is implicitly no-op on SSR.
- */
-
-
-const useViewportListenerSSR = () => {};
 /**
  * When client-side rendering, immediately set the viewport to the correct value as a layout effect so
  * if the viewport isn't the smallest, any SSR-rendered components rerender correctly before anything
@@ -34,8 +24,8 @@ const useViewportListenerSSR = () => {};
  */
 
 
-const useViewportListenerCSR = setViewport => {
-  (0, _react.useLayoutEffect)(() => {
+const useViewportListener = setViewport => {
+  (0, _useSafeLayoutEffect.default)(() => {
     setViewport(lookupViewport());
 
     const onChange = _ref => {
@@ -57,10 +47,7 @@ const useViewportListenerCSR = setViewport => {
       }
     };
   }, [setViewport]);
-}; // Window is a defined global object in both Web and Native client-side, and undefined in SSR
-
+};
 
-const isSSR = typeof window === 'undefined';
-const useViewportListener = isSSR ? useViewportListenerSSR : useViewportListenerCSR;
 var _default = useViewportListener;
 exports.default = _default;

package/lib/utils/animation/useVerticalExpandAnimation.js

@@ -13,6 +13,8 @@ var _Easing = _interopRequireDefault(require("react-native-web/dist/cjs/exports/
 
 var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
 
+var _useSafeLayoutEffect = _interopRequireDefault(require("../useSafeLayoutEffect"));
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
 // TODO: systematise animations
@@ -32,7 +34,7 @@ function useVerticalExpandAnimation(_ref) {
     expandDuration,
     collapseDuration
   } = tokens;
-  (0, _react.useLayoutEffect)(() => {
+  (0, _useSafeLayoutEffect.default)(() => {
     if (expandStateChanged) {
       setIsAnimating(true);
       setWasExpanded(isExpanded);

package/lib/utils/index.js

@@ -9,6 +9,7 @@ var _exportNames = {
   useHash: true,
   useSpacingScale: true,
   useResponsiveProp: true,
+  useSafeLayoutEffect: true,
   useScrollBlocking: true,
   useUniqueId: true,
   withLinkRouter: true,
@@ -44,6 +45,12 @@ Object.defineProperty(exports, "useResponsiveProp", {
     return _useResponsiveProp.default;
   }
 });
+Object.defineProperty(exports, "useSafeLayoutEffect", {
+  enumerable: true,
+  get: function () {
+    return _useSafeLayoutEffect.default;
+  }
+});
 Object.defineProperty(exports, "useScrollBlocking", {
   enumerable: true,
   get: function () {
@@ -175,6 +182,8 @@ Object.keys(_useResponsiveProp).forEach(function (key) {
   });
 });
 
+var _useSafeLayoutEffect = _interopRequireDefault(require("./useSafeLayoutEffect"));
+
 var _useScrollBlocking = _interopRequireDefault(require("./useScrollBlocking"));
 
 var _useUniqueId = _interopRequireDefault(require("./useUniqueId"));

package/lib/utils/useSafeLayoutEffect.js

@@ -0,0 +1,40 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _react = require("react");
+
+var _HydrationContext = require("../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 = (0, _HydrationContext.useHydrationContext)(); // Callback updates and effect re-runs when deps array content changes, like useEffect.
+
+  /* eslint-disable-next-line react-hooks/exhaustive-deps */
+
+  const callback = (0, _react.useCallback)(fn, deps);
+  (0, _react.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]);
+};
+var _default = useSafeLayoutEffect;
+exports.default = _default;

package/lib-module/BaseProvider/HydrationContext.js

@@ -0,0 +1,51 @@
+import React, { createContext, useContext, useEffect, useState } from 'react';
+import PropTypes from 'prop-types';
+import Platform from "react-native-web/dist/exports/Platform";
+import { jsx as _jsx } from "react/jsx-runtime";
+const HydrationContext = /*#__PURE__*/createContext();
+const isSSR = typeof window === 'undefined';
+
+const hasWebStyleTag = () => {
+  var _document;
+
+  if (isSSR || Platform.OS !== 'web' || typeof document !== 'object') {
+    return false;
+  }
+
+  return Boolean((_document = document) === null || _document === void 0 ? void 0 : _document.getElementById('react-native-stylesheet'));
+};
+/**
+ * Returns true if this render cycle is the hydration of existing SSR content.
+ *
+ * Use this when changing how content renders based on data that is instantly available
+ * during the very first client-side render or hydration, but not available on the server,
+ * to ensure no changes happen until the original SSR DOM has been hydrated.
+ */
+
+
+export const useHydrationContext = () => useContext(HydrationContext);
+/**
+ * Allows components and hooks to observe if SSR hydration is currently in progress
+ * and if so, to re-render with content that differs to the server when it is complete.
+ */
+
+export const HydrationProvider = _ref => {
+  let {
+    children
+  } = _ref;
+  const [hasMounted, setHasMounted] = useState(false);
+  useEffect(() => {
+    setHasMounted(true);
+  }, []); // If we've got a HydrationProvider inside a HydrationProvider somehow, defer to the top one
+
+  const valueFromAncestor = useHydrationContext();
+  const isHydrating = valueFromAncestor !== null && valueFromAncestor !== void 0 ? valueFromAncestor : Boolean(!hasMounted && hasWebStyleTag());
+  return /*#__PURE__*/_jsx(HydrationContext.Provider, {
+    value: isHydrating,
+    children: children
+  });
+};
+HydrationProvider.propTypes = {
+  children: PropTypes.node
+};
+export default HydrationProvider;

package/lib-module/BaseProvider/index.js

@@ -6,6 +6,7 @@ import { PortalProvider } from '@gorhom/portal';
 import A11yInfoProvider from '../A11yInfoProvider';
 import ViewportProvider from '../ViewportProvider';
 import ThemeProvider from '../ThemeProvider';
+import { HydrationProvider } from './HydrationContext';
 import { jsx as _jsx } from "react/jsx-runtime";
 
 const BaseProvider = _ref => {
@@ -14,13 +15,15 @@ const BaseProvider = _ref => {
     children,
     themeOptions
   } = _ref;
-  return /*#__PURE__*/_jsx(A11yInfoProvider, {
-    children: /*#__PURE__*/_jsx(ViewportProvider, {
-      children: /*#__PURE__*/_jsx(ThemeProvider, {
-        defaultTheme: defaultTheme,
-        themeOptions: themeOptions,
-        children: /*#__PURE__*/_jsx(PortalProvider, {
-          children: children
+  return /*#__PURE__*/_jsx(HydrationProvider, {
+    children: /*#__PURE__*/_jsx(A11yInfoProvider, {
+      children: /*#__PURE__*/_jsx(ViewportProvider, {
+        children: /*#__PURE__*/_jsx(ThemeProvider, {
+          defaultTheme: defaultTheme,
+          themeOptions: themeOptions,
+          children: /*#__PURE__*/_jsx(PortalProvider, {
+            children: children
+          })
         })
       })
     })

package/lib-module/Search/Search.js

@@ -135,10 +135,18 @@ const Search = /*#__PURE__*/forwardRef((_ref4, ref) => {
   const a11yLabelText = accessibilityLabel || getCopy('accessibilityLabel'); // Placeholder is optional and may be unset by passing an empty string
 
   const placeholderText = placeholder !== null && placeholder !== void 0 ? placeholder : a11yLabelText;
+  const {
+    nativeID,
+    testID,
+    ...containerProps
+  } = selectContainerProps(rest);
   return /*#__PURE__*/_jsxs(View, {
     style: staticStyles.container,
-    ...selectContainerProps(rest),
-    children: [/*#__PURE__*/_jsx(TextInputBase, { ...selectInputProps(rest),
+    ...containerProps,
+    children: [/*#__PURE__*/_jsx(TextInputBase, {
+      nativeID: nativeID,
+      testID: testID,
+      ...selectInputProps(rest),
       ref: ref,
       tokens: appearances => selectInputTokens({
         searchTokens: getThemeTokens(appearances),

package/lib-module/StackView/StackWrap.js

@@ -1,14 +1,15 @@
-import React, { forwardRef } from 'react';
+import React, { forwardRef, useState } from 'react';
 import Platform from "react-native-web/dist/exports/Platform";
+import useSafeLayoutEffect from '../utils/useSafeLayoutEffect';
 import StackWrapBox from './StackWrapBox';
 import StackWrapGap from './StackWrapGap'; // In Jest/CI/SSR, global CSS isn't always available and doesn't always have .supports method
 
 import { jsx as _jsx } from "react/jsx-runtime";
 
-const cssSupports = function () {
+const cssSupports = (property, value) => {
   var _window$CSS;
 
-  return typeof window !== 'undefined' && typeof ((_window$CSS = window.CSS) === null || _window$CSS === void 0 ? void 0 : _window$CSS.supports) === 'function' && window.CSS.supports(...arguments);
+  return Platform.OS === 'web' && typeof window !== 'undefined' && typeof ((_window$CSS = window.CSS) === null || _window$CSS === void 0 ? void 0 : _window$CSS.supports) === 'function' && window.CSS.supports(property, value);
 }; // CSS.supports needs an example of the type of value you intend to use.
 // Will be an integer appended `px` after hooks and JSX styles are resolved.
 
@@ -25,22 +26,24 @@ const exampleGapValue = '1px';
 const StackWrap = /*#__PURE__*/forwardRef((props, ref) => {
   var _props$gap;
 
+  const [canUseCSSGap, setCanUseCSSGap] = useState(false);
   const {
     space
   } = props; // Don't apply separate gap if `null` or `undefined`, so can be unset in Storybook etc
 
   const gap = (_props$gap = props.gap) !== null && _props$gap !== void 0 ? _props$gap : space;
-  const canUseCSSGap = Platform.OS === 'web' && gap === space && cssSupports('gap', exampleGapValue);
-  return canUseCSSGap ?
-  /*#__PURE__*/
-  // If possible, use the cleaner implementation that applies CSS `gap` styles to the container.
-  _jsx(StackWrapGap, {
-    ref: ref,
-    ...props
-  }) :
-  /*#__PURE__*/
+  const gapEqualsSpace = gap === space; // If possible, use the cleaner implementation that applies CSS `gap` styles to the container,
+  // preserving direct parent-child relationships between the container and each item, which
+  // can result in clearer descriptions on some screen readers (e.g. radio "X of Y" on MacOS).
   // Else, use the fallback implementation which renders a `Box` component around each child.
-  _jsx(StackWrapBox, {
+
+  const Component = canUseCSSGap ? StackWrapGap : StackWrapBox; // In SSR, the type of implementation must match the server during hydration, but
+  // the server can't know if gap is supported, so never use it until after hydration.
+
+  useSafeLayoutEffect(() => {
+    setCanUseCSSGap(gapEqualsSpace && cssSupports('gap', exampleGapValue));
+  }, [gapEqualsSpace]);
+  return /*#__PURE__*/_jsx(Component, {
     ref: ref,
     ...props
   });

package/lib-module/ViewportProvider/useViewportListener.js

@@ -1,20 +1,10 @@
-import { useLayoutEffect } from 'react';
 import Dimensions from "react-native-web/dist/exports/Dimensions";
-import { viewports } from '@telus-uds/system-constants'; // Use Dimensions instead of useWindowDimensions because useWindowDimensions forces context
+import { viewports } from '@telus-uds/system-constants';
+import useSafeLayoutEffect from '../utils/useSafeLayoutEffect'; // Use Dimensions instead of useWindowDimensions because useWindowDimensions forces context
 // to update on every pixel change during window resize; but we only want rerenders to occur
 // when a viewport threshold has been crossed.
 
 const lookupViewport = () => viewports.select(Dimensions.get('window').width);
-/**
- * In SSR, React gets spooked if it sees `useLayoutEffect` and fires warnings assuming the
- * developer doesn't realise the effect won't run: https://reactjs.org/link/uselayouteffect-ssr
- *
- * To avoid these warnings while still conforming to the rules of hooks, always use this
- * explicitly no-op hook, instead of the useLayoutEffect that is implicitly no-op on SSR.
- */
-
-
-const useViewportListenerSSR = () => {};
 /**
  * When client-side rendering, immediately set the viewport to the correct value as a layout effect so
  * if the viewport isn't the smallest, any SSR-rendered components rerender correctly before anything
@@ -22,8 +12,8 @@ const useViewportListenerSSR = () => {};
  */
 
 
-const useViewportListenerCSR = setViewport => {
-  useLayoutEffect(() => {
+const useViewportListener = setViewport => {
+  useSafeLayoutEffect(() => {
     setViewport(lookupViewport());
 
     const onChange = _ref => {
@@ -44,9 +34,6 @@ const useViewportListenerCSR = setViewport => {
       }
     };
   }, [setViewport]);
-}; // Window is a defined global object in both Web and Native client-side, and undefined in SSR
-
+};
 
-const isSSR = typeof window === 'undefined';
-const useViewportListener = isSSR ? useViewportListenerSSR : useViewportListenerCSR;
 export default useViewportListener;

package/lib-module/utils/animation/useVerticalExpandAnimation.js

@@ -1,7 +1,8 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import Animated from "react-native-web/dist/exports/Animated";
 import Easing from "react-native-web/dist/exports/Easing";
-import Platform from "react-native-web/dist/exports/Platform"; // TODO: systematise animations
+import Platform from "react-native-web/dist/exports/Platform";
+import useSafeLayoutEffect from '../useSafeLayoutEffect'; // TODO: systematise animations
 // https://github.com/telus/universal-design-system/issues/487
 
 function useVerticalExpandAnimation(_ref) {
@@ -19,7 +20,7 @@ function useVerticalExpandAnimation(_ref) {
     expandDuration,
     collapseDuration
   } = tokens;
-  useLayoutEffect(() => {
+  useSafeLayoutEffect(() => {
     if (expandStateChanged) {
       setIsAnimating(true);
       setWasExpanded(isExpanded);

package/lib-module/utils/index.js

@@ -9,6 +9,7 @@ export { default as useCopy } from './useCopy';
 export { default as useHash } from './useHash';
 export { default as useSpacingScale } from './useSpacingScale';
 export { default as useResponsiveProp } from './useResponsiveProp';
+export { default as useSafeLayoutEffect } from './useSafeLayoutEffect';
 export { default as useScrollBlocking } from './useScrollBlocking';
 export * from './useResponsiveProp';
 export { default as useUniqueId } from './useUniqueId';

package/lib-module/utils/useSafeLayoutEffect.js

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

@@ -67,5 +67,5 @@
   "standard-engine": {
     "skip": true
   },
-  "version": "1.17.0"
+  "version": "1.18.1"
 }

package/src/BaseProvider/HydrationContext.jsx

@@ -0,0 +1,44 @@
+import React, { createContext, useContext, useEffect, useState } from 'react'
+import PropTypes from 'prop-types'
+import { Platform } from 'react-native'
+
+const HydrationContext = createContext()
+const isSSR = typeof window === 'undefined'
+const hasWebStyleTag = () => {
+  if (isSSR || Platform.OS !== 'web' || typeof document !== 'object') {
+    return false
+  }
+  return Boolean(document?.getElementById('react-native-stylesheet'))
+}
+
+/**
+ * Returns true if this render cycle is the hydration of existing SSR content.
+ *
+ * Use this when changing how content renders based on data that is instantly available
+ * during the very first client-side render or hydration, but not available on the server,
+ * to ensure no changes happen until the original SSR DOM has been hydrated.
+ */
+export const useHydrationContext = () => useContext(HydrationContext)
+
+/**
+ * Allows components and hooks to observe if SSR hydration is currently in progress
+ * and if so, to re-render with content that differs to the server when it is complete.
+ */
+export const HydrationProvider = ({ children }) => {
+  const [hasMounted, setHasMounted] = useState(false)
+  useEffect(() => {
+    setHasMounted(true)
+  }, [])
+
+  // If we've got a HydrationProvider inside a HydrationProvider somehow, defer to the top one
+  const valueFromAncestor = useHydrationContext()
+
+  const isHydrating = valueFromAncestor ?? Boolean(!hasMounted && hasWebStyleTag())
+  return <HydrationContext.Provider value={isHydrating}>{children}</HydrationContext.Provider>
+}
+
+HydrationProvider.propTypes = {
+  children: PropTypes.node
+}
+
+export default HydrationProvider

package/src/BaseProvider/index.jsx

@@ -4,15 +4,18 @@ import { PortalProvider } from '@gorhom/portal'
 import A11yInfoProvider from '../A11yInfoProvider'
 import ViewportProvider from '../ViewportProvider'
 import ThemeProvider from '../ThemeProvider'
+import { HydrationProvider } from './HydrationContext'
 
 const BaseProvider = ({ defaultTheme, children, themeOptions }) => (
-  <A11yInfoProvider>
-    <ViewportProvider>
-      <ThemeProvider defaultTheme={defaultTheme} themeOptions={themeOptions}>
-        <PortalProvider>{children}</PortalProvider>
-      </ThemeProvider>
-    </ViewportProvider>
-  </A11yInfoProvider>
+  <HydrationProvider>
+    <A11yInfoProvider>
+      <ViewportProvider>
+        <ThemeProvider defaultTheme={defaultTheme} themeOptions={themeOptions}>
+          <PortalProvider>{children}</PortalProvider>
+        </ThemeProvider>
+      </ViewportProvider>
+    </A11yInfoProvider>
+  </HydrationProvider>
 )
 
 BaseProvider.propTypes = {

package/src/Search/Search.jsx

@@ -123,10 +123,13 @@ const Search = forwardRef(
     const a11yLabelText = accessibilityLabel || getCopy('accessibilityLabel')
     // Placeholder is optional and may be unset by passing an empty string
     const placeholderText = placeholder ?? a11yLabelText
+    const { nativeID, testID, ...containerProps } = selectContainerProps(rest)
 
     return (
-      <View style={staticStyles.container} {...selectContainerProps(rest)}>
+      <View style={staticStyles.container} {...containerProps}>
         <TextInputBase
+          nativeID={nativeID}
+          testID={testID}
           {...selectInputProps(rest)}
           ref={ref}
           tokens={(appearances) =>

package/src/StackView/StackWrap.jsx

@@ -1,14 +1,16 @@
-import React, { forwardRef } from 'react'
+import React, { forwardRef, useState } from 'react'
 import { Platform } from 'react-native'
 
+import useSafeLayoutEffect from '../utils/useSafeLayoutEffect'
 import StackWrapBox from './StackWrapBox'
 import StackWrapGap from './StackWrapGap'
 
 // In Jest/CI/SSR, global CSS isn't always available and doesn't always have .supports method
-const cssSupports = (...args) =>
+const cssSupports = (property, value) =>
+  Platform.OS === 'web' &&
   typeof window !== 'undefined' &&
   typeof window.CSS?.supports === 'function' &&
-  window.CSS.supports(...args)
+  window.CSS.supports(property, value)
 
 // CSS.supports needs an example of the type of value you intend to use.
 // Will be an integer appended `px` after hooks and JSX styles are resolved.
@@ -22,19 +24,24 @@ const exampleGapValue = '1px'
  * If a different spacing is desired between wrapped lines, pass a spacing value to the `gap` prop.
  */
 const StackWrap = forwardRef((props, ref) => {
+  const [canUseCSSGap, setCanUseCSSGap] = useState(false)
   const { space } = props
   // Don't apply separate gap if `null` or `undefined`, so can be unset in Storybook etc
   const gap = props.gap ?? space
-
-  const canUseCSSGap = Platform.OS === 'web' && gap === space && cssSupports('gap', exampleGapValue)
-
-  return canUseCSSGap ? (
-    // If possible, use the cleaner implementation that applies CSS `gap` styles to the container.
-    <StackWrapGap ref={ref} {...props} />
-  ) : (
-    // Else, use the fallback implementation which renders a `Box` component around each child.
-    <StackWrapBox ref={ref} {...props} />
-  )
+  const gapEqualsSpace = gap === space
+
+  // If possible, use the cleaner implementation that applies CSS `gap` styles to the container,
+  // preserving direct parent-child relationships between the container and each item, which
+  // can result in clearer descriptions on some screen readers (e.g. radio "X of Y" on MacOS).
+  // Else, use the fallback implementation which renders a `Box` component around each child.
+  const Component = canUseCSSGap ? StackWrapGap : StackWrapBox
+  // In SSR, the type of implementation must match the server during hydration, but
+  // the server can't know if gap is supported, so never use it until after hydration.
+  useSafeLayoutEffect(() => {
+    setCanUseCSSGap(gapEqualsSpace && cssSupports('gap', exampleGapValue))
+  }, [gapEqualsSpace])
+
+  return <Component ref={ref} {...props} />
 })
 StackWrap.displayName = 'StackWrap'
 

package/src/ViewportProvider/useViewportListener.js

@@ -1,28 +1,20 @@
-import { useLayoutEffect } from 'react'
 import { Dimensions } from 'react-native'
 import { viewports } from '@telus-uds/system-constants'
 
+import useSafeLayoutEffect from '../utils/useSafeLayoutEffect'
+
 // Use Dimensions instead of useWindowDimensions because useWindowDimensions forces context
 // to update on every pixel change during window resize; but we only want rerenders to occur
 // when a viewport threshold has been crossed.
 const lookupViewport = () => viewports.select(Dimensions.get('window').width)
 
-/**
- * In SSR, React gets spooked if it sees `useLayoutEffect` and fires warnings assuming the
- * developer doesn't realise the effect won't run: https://reactjs.org/link/uselayouteffect-ssr
- *
- * To avoid these warnings while still conforming to the rules of hooks, always use this
- * explicitly no-op hook, instead of the useLayoutEffect that is implicitly no-op on SSR.
- */
-const useViewportListenerSSR = () => {}
-
 /**
  * When client-side rendering, immediately set the viewport to the correct value as a layout effect so
  * if the viewport isn't the smallest, any SSR-rendered components rerender correctly before anything
  * is shown to the user. Then bind events to update the viewport if it changes.
  */
-const useViewportListenerCSR = (setViewport) => {
-  useLayoutEffect(() => {
+const useViewportListener = (setViewport) => {
+  useSafeLayoutEffect(() => {
     setViewport(lookupViewport())
 
     const onChange = ({ window }) => setViewport(viewports.select(window.width))
@@ -41,8 +33,4 @@ const useViewportListenerCSR = (setViewport) => {
   }, [setViewport])
 }
 
-// Window is a defined global object in both Web and Native client-side, and undefined in SSR
-const isSSR = typeof window === 'undefined'
-const useViewportListener = isSSR ? useViewportListenerSSR : useViewportListenerCSR
-
 export default useViewportListener

package/src/utils/animation/useVerticalExpandAnimation.js

@@ -1,6 +1,8 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { Animated, Easing, Platform } from 'react-native'
 
+import useSafeLayoutEffect from '../useSafeLayoutEffect'
+
 // TODO: systematise animations
 // https://github.com/telus/universal-design-system/issues/487
 function useVerticalExpandAnimation({ containerHeight, isExpanded, tokens }) {
@@ -13,7 +15,7 @@ function useVerticalExpandAnimation({ containerHeight, isExpanded, tokens }) {
 
   const { expandDuration, collapseDuration } = tokens
 
-  useLayoutEffect(() => {
+  useSafeLayoutEffect(() => {
     if (expandStateChanged) {
       setIsAnimating(true)
       setWasExpanded(isExpanded)

package/src/utils/index.js

@@ -10,6 +10,7 @@ export { default as useCopy } from './useCopy'
 export { default as useHash } from './useHash'
 export { default as useSpacingScale } from './useSpacingScale'
 export { default as useResponsiveProp } from './useResponsiveProp'
+export { default as useSafeLayoutEffect } from './useSafeLayoutEffect'
 export { default as useScrollBlocking } from './useScrollBlocking'
 export * from './useResponsiveProp'
 export { default as useUniqueId } from './useUniqueId'

package/src/utils/useSafeLayoutEffect.js

@@ -0,0 +1,31 @@
+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
+  : (fn, deps = []) => {
+      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