@skyscanner/backpack-web 42.27.0 → 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'.
@@ -71,6 +75,19 @@ const FALLBACK_LOCALE_BY_DIRECTION = {
 // Intl.Locale.textInfo is unavailable (Node < 22, older browsers).
 const RTL_LANGUAGE_SUBTAGS = new Set(['ar', 'he', 'fa', 'ur', 'yi', 'iw', 'ps', 'sd', 'ug', 'ku']);
 
+// Returns true when `locale` is a BCP 47 string that Intl.Locale accepts.
+// Ark's LocaleProvider calls `new Intl.Locale(locale)` without a try/catch,
+// so any value we hand it must be validated here first or it throws
+// "Incorrect locale information provided".
+const isValidLocale = locale => {
+  try {
+    // Reading a property on the result (rather than bare `new`) satisfies the no-new lint rule.
+    return Boolean(new Intl.Locale(locale).baseName);
+  } catch {
+    return false;
+  }
+};
+
 // Returns the text direction implied by a BCP 47 locale string.
 // Uses Intl.Locale.textInfo when available (Chrome 99+, Safari 15.4+, Firefox 126+, Node 22+);
 // falls back to a known-RTL-subtag lookup.
@@ -88,11 +105,18 @@ const getLangDir = locale => {
 //
 // Priority rules:
 //   1. If html[dir] is explicitly set:
-//      - Use html[lang] only when its direction is consistent with html[dir].
+//      - Use html[lang] only when it is a valid locale AND its direction is
+//        consistent with html[dir].
 //      - Otherwise fall back to FALLBACK_LOCALE_BY_DIRECTION[dir].
 //      This prevents an LTR html[lang] (e.g. 'en' from a page template) from
 //      overriding an explicit html[dir]="rtl" signal (e.g. from a dev RTL toggle).
-//   2. If html[dir] is not set: use html[lang] if present, else 'en-US'.
+//   2. If html[dir] is not set: use html[lang] if it is a valid locale, else 'en-US'.
+//
+// Every value returned here is validated with isValidLocale() because Ark's
+// LocaleProvider passes it straight to `new Intl.Locale()`, which throws on
+// malformed input (e.g. '', '123', 'en_US'). An unvalidated value crashes the
+// provider, and when the ErrorBoundary fallback also mounts BpkProvider the same
+// bad value is re-read on every remount, producing an indefinite crash loop.
 //
 // SSR-safe: returns 'en-US' when document is unavailable.
 const getArkLocale = () => {
@@ -100,17 +124,12 @@ const getArkLocale = () => {
   const explicitDir = document.documentElement.getAttribute('dir');
   const lang = document.documentElement.getAttribute('lang');
   if (explicitDir === 'rtl' || explicitDir === 'ltr') {
-    if (lang && getLangDir(lang) === explicitDir) return lang;
-    return FALLBACK_LOCALE_BY_DIRECTION[explicitDir];
-  }
-  if (lang) {
-    try {
-      const locale = new Intl.Locale(lang);
-      if (locale) return lang;
-    } catch {
-      // Invalid locale string — fall through to default
+    if (lang && isValidLocale(lang) && getLangDir(lang) === explicitDir) {
+      return lang;
     }
+    return FALLBACK_LOCALE_BY_DIRECTION[explicitDir];
   }
+  if (lang && isValidLocale(lang)) return lang;
   return 'en-US';
 };
 
@@ -138,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.)
  *
@@ -145,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();
 
@@ -162,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, {
@@ -175,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.0",
+  "version": "42.27.2",
   "description": "Backpack Design System web library",
   "repository": {
     "type": "git",