@skyscanner/backpack-web 42.27.1 → 42.27.2

package/bpk-component-layout/index.d.ts

@@ -1,4 +1,4 @@
-export { BpkProvider } from './src/BpkProvider';
+export { BpkProvider, BpkEmotionCacheContext } from './src/BpkProvider';
 export { BpkBox } from './src/BpkBox';
 export { BpkVessel } from './src/BpkVessel';
 export { BpkFlex } from './src/BpkFlex';

package/bpk-component-layout/index.js

@@ -16,7 +16,7 @@
  * limitations under the License.
  */
 
-export { BpkProvider } from "./src/BpkProvider";
+export { BpkProvider, BpkEmotionCacheContext } from "./src/BpkProvider";
 export { BpkBox } from "./src/BpkBox";
 export { BpkVessel } from "./src/BpkVessel";
 export { BpkFlex } from "./src/BpkFlex";

package/bpk-component-layout/src/BpkProvider.d.ts

@@ -1,11 +1,14 @@
-import type { ReactElement, ReactNode } from 'react';
+import type { ReactNode, ReactElement } from 'react';
+import type { EmotionCache } from '@emotion/cache';
 export interface BpkProviderProps {
     children: ReactNode;
 }
+export declare const BpkEmotionCacheContext: import("react").Context<EmotionCache | null>;
 /**
  * BpkProvider - Provides context for Backpack layout and Ark-based components.
  *
  * Wraps children with:
+ * - Emotion CacheProvider (own cache, or external cache injected via BpkEmotionCacheContext)
  * - Chakra UI system context (for layout components: BpkFlex, BpkGrid, etc.)
  * - Ark UI LocaleProvider (for Ark-based components: BpkCheckboxV2, BpkSegmentedControlV2, etc.)
  *
@@ -13,6 +16,11 @@ export interface BpkProviderProps {
  * the appropriate locale to Ark's LocaleProvider. All Ark-based components in the
  * tree render correctly in RTL without requiring additional wrapping or prop changes.
  *
+ * External cache injection: host apps can supply an Emotion cache via
+ * BpkEmotionCacheContext. When a non-null value is provided, BpkProvider uses it
+ * directly and skips creating its own cache. This allows the host to swap in a
+ * fresh cache after a hydration error so all Backpack styles are re-injected.
+ *
  * @param {BpkProviderProps} props - The provider props.
  * @returns {ReactElement} The provider wrapping its children with Chakra and Ark context.
  */

package/bpk-component-layout/src/BpkProvider.js

@@ -23,6 +23,12 @@ import createCache from '@emotion/cache';
 import { CacheProvider } from '@emotion/react';
 import { createBpkConfig } from "./theme";
 import { jsx as _jsx } from "react/jsx-runtime";
+// Exported so host apps can inject an externally-managed Emotion cache into
+// BpkProvider (e.g. to force re-injection after a hydration error recovery).
+// When a non-null value is provided via this context, BpkProvider operates in
+// "external cache" mode: it skips creating its own cache and delegates to the external one.
+export const BpkEmotionCacheContext = /*#__PURE__*/createContext(null);
+
 /**
  * Creates a Chakra UI system with Backpack token mappings.
  *
@@ -37,6 +43,14 @@ const bpkSystem = createSystem(defaultBaseConfig, createBpkConfig());
 // Force speedy:false + recreate after mount in Cypress. Remove once Emotion /
 // React Router 7 provide a cleaner hydration story. Ported from hotels-website#12025.
 
+// `'css'` is shared with Chakra v3's internal key on purpose — keeps this
+// boundary in front of Chakra's auto-created cache.
+const createBpkEmotionCache = speedy => createCache(speedy === undefined ? {
+  key: 'css'
+} : {
+  key: 'css',
+  speedy
+});
 const isCypressEnv = () => {
   if (typeof window === 'undefined') return false;
   const win = window;
@@ -49,16 +63,6 @@ const isCypressEnv = () => {
     return false; // cross-origin parent frame
   }
 };
-
-// `'css'` is shared with Chakra v3's internal key on purpose — keeps this
-// boundary in front of Chakra's auto-created cache.
-const createBpkEmotionCache = speedy => createCache(speedy === undefined ? {
-  key: 'css'
-} : {
-  key: 'css',
-  speedy
-});
-const BpkEmotionCacheContext = /*#__PURE__*/createContext(null);
 // Fallback locale mapping used when no explicit locale is available on the document.
 // Maps DOM direction to minimal BCP 47 locales understood by Ark's isRTL() utility.
 // 'ar-SA' is the minimal RTL locale — Ark only uses it to derive dir='rtl'.
@@ -153,6 +157,7 @@ const useArkLocale = () => {
  * BpkProvider - Provides context for Backpack layout and Ark-based components.
  *
  * Wraps children with:
+ * - Emotion CacheProvider (own cache, or external cache injected via BpkEmotionCacheContext)
  * - Chakra UI system context (for layout components: BpkFlex, BpkGrid, etc.)
  * - Ark UI LocaleProvider (for Ark-based components: BpkCheckboxV2, BpkSegmentedControlV2, etc.)
  *
@@ -160,16 +165,21 @@ const useArkLocale = () => {
  * the appropriate locale to Ark's LocaleProvider. All Ark-based components in the
  * tree render correctly in RTL without requiring additional wrapping or prop changes.
  *
+ * External cache injection: host apps can supply an Emotion cache via
+ * BpkEmotionCacheContext. When a non-null value is provided, BpkProvider uses it
+ * directly and skips creating its own cache. This allows the host to swap in a
+ * fresh cache after a hydration error so all Backpack styles are re-injected.
+ *
  * @param {BpkProviderProps} props - The provider props.
  * @returns {ReactElement} The provider wrapping its children with Chakra and Ark context.
  */
 export const BpkProvider = ({
   children
 }) => {
-  const parentCache = useContext(BpkEmotionCacheContext);
-  const isNested = parentCache !== null;
+  const externalCache = useContext(BpkEmotionCacheContext);
+  const hasExternalCache = externalCache !== null;
   const [isCypress] = useState(isCypressEnv);
-  const [ownCache, setOwnCache] = useState(() => isNested ? parentCache : createBpkEmotionCache(isCypress ? false : undefined));
+  const [ownCache, setOwnCache] = useState(() => hasExternalCache ? externalCache : createBpkEmotionCache(isCypress ? false : undefined));
   const hasRecreated = useRef(false);
   const locale = useArkLocale();
 
@@ -177,12 +187,19 @@ export const BpkProvider = ({
   // nodes the hydrator stripped. `hasRecreated` guards StrictMode double-invoke.
   // Deps stable for provider lifetime → empty array is intentional.
   useEffect(() => {
-    if (isNested || !isCypress) return;
+    if (hasExternalCache || !isCypress) return;
     if (hasRecreated.current) return;
     hasRecreated.current = true;
     setOwnCache(createBpkEmotionCache(false));
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
+
+  // NOTE: if externalCache changes from non-null to null at runtime, ownCache
+  // will still hold the value it was initialised with (the old external cache).
+  // This is intentional: BpkEmotionCacheContext.Provider is expected to be
+  // mounted for the lifetime of the app once set — toggling it off is not a
+  // supported use case. The state initialiser runs only once per mount.
+  const activeCache = hasExternalCache ? externalCache : ownCache;
   const inner = /*#__PURE__*/_jsx(ChakraProvider, {
     value: bpkSystem,
     children: /*#__PURE__*/_jsx(LocaleProvider, {
@@ -190,13 +207,10 @@ export const BpkProvider = ({
       children: children
     })
   });
-  if (isNested) {
-    return inner;
-  }
   return /*#__PURE__*/_jsx(BpkEmotionCacheContext.Provider, {
-    value: ownCache,
+    value: activeCache,
     children: /*#__PURE__*/_jsx(CacheProvider, {
-      value: ownCache,
+      value: activeCache,
       children: inner
     })
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyscanner/backpack-web",
-  "version": "42.27.1",
+  "version": "42.27.2",
   "description": "Backpack Design System web library",
   "repository": {
     "type": "git",