@skyscanner/backpack-web 42.0.0 → 42.2.0

package/bpk-component-icon/scripts/generate-figma-connect.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+/*
+ * Backpack - Skyscanner's Design System
+ *
+ * Copyright 2016 Skyscanner Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Generates Figma Code Connect mappings for Backpack icons.
+ *
+ * This script fetches component metadata from the Figma Icons file and
+ * cross-references it with the icon files in sm/ and lg/ to produce
+ * a single .figma.tsx file that maps every icon to its Figma component.
+ *
+ * Usage:
+ *   FIGMA_ACCESS_TOKEN=<token> node packages/bpk-component-icon/scripts/generate-figma-connect.js
+ *
+ * The generated file is written to:
+ *   packages/bpk-component-icon/BpkIcon.figma.tsx
+ */
+const fs = require('fs');
+const path = require('path');
+const FIGMA_FILE_KEY = 'I9hynSlX2wyrlhceZr7z1u';
+const FIGMA_FILE_NAME = 'Backpack-Icons';
+const FIGMA_BASE_URL = `https://www.figma.com/design/${FIGMA_FILE_KEY}/${FIGMA_FILE_NAME}`;
+const ICON_PKG = path.resolve(__dirname, '..');
+const OUTPUT_FILE = path.join(ICON_PKG, 'BpkIcon.figma.tsx');
+function kebabToPascal(str) {
+  return str.split(/[-]+/).map(part => part.charAt(0).toUpperCase() + part.slice(1)).join('');
+}
+function getIconFiles(dir) {
+  if (!fs.existsSync(dir)) return new Set();
+  return new Set(fs.readdirSync(dir).filter(f => f.endsWith('.jsx')).map(f => f.replace('.jsx', '')));
+}
+async function fetchFigmaComponents() {
+  const token = process.env.FIGMA_ACCESS_TOKEN;
+  if (!token) {
+    console.error('Error: FIGMA_ACCESS_TOKEN environment variable is required.');
+    process.exit(1);
+  }
+  const url = `https://api.figma.com/v1/files/${FIGMA_FILE_KEY}/components`;
+  const res = await fetch(url, {
+    headers: {
+      'X-Figma-Token': token
+    }
+  });
+  if (!res.ok) {
+    console.error(`Figma API error: ${res.status} ${res.statusText}`);
+    process.exit(1);
+  }
+  const data = await res.json();
+  return data.meta.components;
+}
+function groupComponentSets(components) {
+  const sets = {};
+  for (const c of components) {
+    const {
+      name
+    } = c.containing_frame;
+    const setNodeId = c.containing_frame.nodeId;
+    if (!sets[name]) {
+      sets[name] = {
+        nodeId: setNodeId,
+        variants: {},
+        variantProp: null
+      };
+    }
+
+    // Detect the variant property name (most use "Size", one uses "Property 1")
+    const match = c.name.match(/^(.+?)=(\d+)$/);
+    if (match) {
+      const [, variantProp, variantValue] = match;
+      sets[name].variantProp = variantProp;
+      sets[name].variants[variantValue] = c.node_id;
+    }
+  }
+  return sets;
+}
+function figmaUrl(nodeId) {
+  const encoded = nodeId.replace(/:/g, '%3A');
+  return `${FIGMA_BASE_URL}?node-id=${encoded}`;
+}
+
+// Spelling aliases: Figma name → code name
+const SPELLING_ALIASES = {
+  centre: 'center'
+};
+
+/**
+ * Normalize a name by collapsing double-hyphens to single and applying
+ * spelling aliases, so we can fuzzy-match Figma names to code file names.
+ *
+ * @param {string} name - The icon name to normalize.
+ * @returns {string} The normalized name.
+ */
+function normalize(name) {
+  const collapsed = name.replace(/--/g, '-');
+  return collapsed.split('-').map(part => SPELLING_ALIASES[part] || part).join('-');
+}
+
+/**
+ * Find the matching code file name for a Figma icon name.
+ * Tries exact match first, then falls back to normalized matching.
+ *
+ * @param {string} figmaName - The icon name from Figma.
+ * @param {Set<string>} codeIcons - Set of icon file names from code.
+ * @returns {string|null} The matching code file name, or null if not found.
+ */
+function findCodeMatch(figmaName, codeIcons) {
+  if (codeIcons.has(figmaName)) return figmaName;
+  const normalizedFigma = normalize(figmaName);
+  for (const codeName of codeIcons) {
+    if (normalize(codeName) === normalizedFigma) return codeName;
+  }
+  return null;
+}
+function generateFile(iconSets, smIcons, lgIcons) {
+  const entries = [];
+  for (const [name, set] of Object.entries(iconSets).sort(([a], [b]) => a.localeCompare(b))) {
+    const smMatch = set.variants['16'] ? findCodeMatch(name, smIcons) : null;
+    const lgMatch = set.variants['24'] ? findCodeMatch(name, lgIcons) : null;
+    if (smMatch || lgMatch) {
+      entries.push({
+        name: smMatch || lgMatch,
+        figmaName: name,
+        nodeId: set.nodeId,
+        smFile: smMatch,
+        lgFile: lgMatch,
+        variantProp: set.variantProp || 'Size'
+      });
+    }
+  }
+  if (entries.length === 0) {
+    console.error('No matching icons found between Figma and code.');
+    process.exit(1);
+  }
+
+  // Build imports — interleaved and sorted alphabetically by import path
+  // to satisfy eslint import/order rules
+  const allImports = [];
+  for (const e of entries) {
+    if (e.lgFile) {
+      const pascal = kebabToPascal(e.lgFile);
+      allImports.push(`import BpkLarge${pascal}Icon from './lg/${e.lgFile}';`);
+    }
+    if (e.smFile) {
+      const pascal = kebabToPascal(e.smFile);
+      allImports.push(`import BpkSmall${pascal}Icon from './sm/${e.smFile}';`);
+    }
+  }
+  allImports.sort((a, b) => {
+    const pathA = a.match(/from '(.+)'/)[1];
+    const pathB = b.match(/from '(.+)'/)[1];
+    return pathA.localeCompare(pathB);
+  });
+
+  // Build connect calls
+  const connectCalls = [];
+  for (const e of entries) {
+    const url = figmaUrl(e.nodeId);
+    const prop = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(e.variantProp) ? e.variantProp : JSON.stringify(e.variantProp);
+    if (e.smFile && e.lgFile) {
+      const smPascal = kebabToPascal(e.smFile);
+      const lgPascal = kebabToPascal(e.lgFile);
+      connectCalls.push(`figma.connect(
+  BpkSmall${smPascal}Icon,
+  "${url}",
+  {
+    variant: { ${prop}: "16" },
+    example: () => <BpkSmall${smPascal}Icon />,
+  },
+)
+
+figma.connect(
+  BpkLarge${lgPascal}Icon,
+  "${url}",
+  {
+    variant: { ${prop}: "24" },
+    example: () => <BpkLarge${lgPascal}Icon />,
+  },
+)`);
+    } else if (e.smFile) {
+      const smPascal = kebabToPascal(e.smFile);
+      const variantLine = prop ? `    variant: { ${prop}: "16" },\n` : '';
+      connectCalls.push(`figma.connect(
+  BpkSmall${smPascal}Icon,
+  "${url}",
+  {
+${variantLine}    example: () => <BpkSmall${smPascal}Icon />,
+  },
+)`);
+    } else if (e.lgFile) {
+      const lgPascal = kebabToPascal(e.lgFile);
+      const variantLine = prop ? `    variant: { ${prop}: "24" },\n` : '';
+      connectCalls.push(`figma.connect(
+  BpkLarge${lgPascal}Icon,
+  "${url}",
+  {
+${variantLine}    example: () => <BpkLarge${lgPascal}Icon />,
+  },
+)`);
+    }
+  }
+  const content = `/*
+ * Backpack - Skyscanner's Design System
+ *
+ * Copyright 2016 Skyscanner Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// AUTO-GENERATED by scripts/generate-figma-connect.js — do not edit manually.
+
+import figma from '@figma/code-connect'
+
+${allImports.join('\n')}
+
+${connectCalls.join('\n\n')}
+`;
+  return {
+    content,
+    count: entries.length
+  };
+}
+async function main() {
+  console.log('Fetching icon components from Figma...');
+  const components = await fetchFigmaComponents();
+  console.log(`Found ${components.length} components in Figma.`);
+  const iconSets = groupComponentSets(components);
+  console.log(`Grouped into ${Object.keys(iconSets).length} icon sets.`);
+  const smIcons = getIconFiles(path.join(ICON_PKG, 'sm'));
+  const lgIcons = getIconFiles(path.join(ICON_PKG, 'lg'));
+  console.log(`Code icons: ${smIcons.size} sm, ${lgIcons.size} lg.`);
+  const {
+    content,
+    count
+  } = generateFile(iconSets, smIcons, lgIcons);
+  fs.writeFileSync(OUTPUT_FILE, content);
+  console.log(`Generated ${OUTPUT_FILE} with ${count} icon mappings.`);
+}
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/bpk-component-inset-banner/index.d.ts

@@ -2,7 +2,10 @@ import BpkInsetBanner, { type Props as BpkInsetBannerProps } from './src/BpkInse
 import BpkInsetBannerSponsored from './src/BpkInsetBannerV2/BpkInsetBannerSponsored';
 import { type CommonProps as BpkInsetBannerSponsoredProps } from './src/BpkInsetBannerV2/common-types';
 import { VARIANT } from './src/BpkInsetBannerV2/common-types';
+import BpkInsetBannerV3 from './src/BpkInsetBannerV3/BpkInsetBannerV3';
+import type { RootProps as BpkInsetBannerV3RootProps, HeaderProps as BpkInsetBannerV3HeaderProps, LeadingAccessoryProps as BpkInsetBannerV3LeadingAccessoryProps, ContentProps as BpkInsetBannerV3ContentProps, BodyProps as BpkInsetBannerV3BodyProps, TrailingAccessoryProps as BpkInsetBannerV3TrailingAccessoryProps } from './src/BpkInsetBannerV3/BpkInsetBannerV3';
 export type { BpkInsetBannerProps };
 export type { BpkInsetBannerSponsoredProps };
+export type { BpkInsetBannerV3RootProps, BpkInsetBannerV3HeaderProps, BpkInsetBannerV3LeadingAccessoryProps, BpkInsetBannerV3ContentProps, BpkInsetBannerV3BodyProps, BpkInsetBannerV3TrailingAccessoryProps, };
 export { VARIANT };
-export { BpkInsetBannerSponsored, BpkInsetBanner };
+export { BpkInsetBannerSponsored, BpkInsetBanner, BpkInsetBannerV3 };

package/bpk-component-inset-banner/index.js

@@ -19,5 +19,6 @@
 import BpkInsetBanner from "./src/BpkInsetBanner";
 import BpkInsetBannerSponsored from "./src/BpkInsetBannerV2/BpkInsetBannerSponsored";
 import { VARIANT } from "./src/BpkInsetBannerV2/common-types";
+import BpkInsetBannerV3 from "./src/BpkInsetBannerV3/BpkInsetBannerV3";
 export { VARIANT };
-export { BpkInsetBannerSponsored, BpkInsetBanner };
+export { BpkInsetBannerSponsored, BpkInsetBanner, BpkInsetBannerV3 };

package/bpk-component-inset-banner/src/BpkInsetBannerV3/BpkInsetBannerV3.d.ts

@@ -0,0 +1,56 @@
+import type { ComponentPropsWithoutRef, MouseEvent, ReactNode } from 'react';
+export type BodyProps = {
+    children: ReactNode;
+    bleed?: boolean;
+    backgroundColor?: string;
+};
+export type RootProps = Omit<ComponentPropsWithoutRef<'div'>, 'className' | 'style' | 'children'> & {
+    children: ReactNode;
+    backgroundColor?: string;
+    textVariant?: 'on-light' | 'on-dark';
+};
+export type HeaderProps = {
+    children: ReactNode;
+    layout?: 'horizontal' | 'vertical';
+};
+export type LeadingAccessoryProps = {
+    children: ReactNode;
+};
+export type ContentProps = {
+    children: ReactNode;
+};
+type InteractiveTrailingAccessoryProps = Omit<ComponentPropsWithoutRef<'button'>, 'className' | 'style' | 'children' | 'type' | 'onClick'> & {
+    children: ReactNode;
+    onClick: (event: MouseEvent<HTMLButtonElement>) => void;
+    'aria-label'?: string;
+};
+type StaticTrailingAccessoryProps = Omit<ComponentPropsWithoutRef<'div'>, 'className' | 'style' | 'children'> & {
+    children: ReactNode;
+    onClick?: never;
+};
+export type TrailingAccessoryProps = InteractiveTrailingAccessoryProps | StaticTrailingAccessoryProps;
+declare const BpkInsetBannerV3: {
+    Root: import("react").ForwardRefExoticComponent<Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "className" | "style" | "children"> & {
+        children: ReactNode;
+        backgroundColor?: string;
+        textVariant?: "on-light" | "on-dark";
+    } & import("react").RefAttributes<HTMLDivElement>>;
+    Header: {
+        ({ children, layout }: HeaderProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    LeadingAccessory: {
+        ({ children }: LeadingAccessoryProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    Content: {
+        ({ children }: ContentProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    Body: {
+        ({ backgroundColor, bleed, children }: BodyProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    TrailingAccessory: import("react").ForwardRefExoticComponent<TrailingAccessoryProps & import("react").RefAttributes<HTMLDivElement | HTMLButtonElement>>;
+};
+export default BpkInsetBannerV3;

package/bpk-component-inset-banner/src/BpkInsetBannerV3/BpkInsetBannerV3.js

@@ -0,0 +1,118 @@
+/*
+ * Backpack - Skyscanner's Design System
+ *
+ * Copyright 2016 Skyscanner Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { forwardRef } from 'react';
+import { cssModules, getDataComponentAttribute } from "../../../bpk-react-utils";
+import STYLES from "./BpkInsetBannerV3.module.css";
+import { jsx as _jsx } from "react/jsx-runtime";
+const getClassName = cssModules(STYLES);
+const Body = ({
+  backgroundColor,
+  bleed,
+  children
+}) => /*#__PURE__*/_jsx("div", {
+  ...getDataComponentAttribute('InsetBannerV3.Body'),
+  className: getClassName('bpk-inset-banner-v3__body', bleed && 'bpk-inset-banner-v3__body--bleed'),
+  style: backgroundColor ? {
+    backgroundColor
+  } : undefined,
+  children: children
+});
+Body.displayName = 'BpkInsetBannerV3.Body';
+const Root = /*#__PURE__*/forwardRef(({
+  backgroundColor,
+  children,
+  textVariant = 'on-light',
+  ...rest
+}, ref) => /*#__PURE__*/_jsx("div", {
+  ref: ref,
+  ...getDataComponentAttribute('InsetBannerV3'),
+  ...rest,
+  className: getClassName('bpk-inset-banner-v3', `bpk-inset-banner-v3--${textVariant}`),
+  style: backgroundColor ? {
+    backgroundColor
+  } : undefined,
+  children: children
+}));
+Root.displayName = 'BpkInsetBannerV3.Root';
+const Header = ({
+  children,
+  layout
+}) => /*#__PURE__*/_jsx("div", {
+  ...getDataComponentAttribute('InsetBannerV3.Header'),
+  className: getClassName('bpk-inset-banner-v3__header', layout === 'horizontal' && 'bpk-inset-banner-v3__header--horizontal', layout === 'vertical' && 'bpk-inset-banner-v3__header--vertical'),
+  children: children
+});
+Header.displayName = 'BpkInsetBannerV3.Header';
+const LeadingAccessory = ({
+  children
+}) => /*#__PURE__*/_jsx("div", {
+  ...getDataComponentAttribute('InsetBannerV3.LeadingAccessory'),
+  className: getClassName('bpk-inset-banner-v3__leading-accessory'),
+  children: children
+});
+LeadingAccessory.displayName = 'BpkInsetBannerV3.LeadingAccessory';
+const Content = ({
+  children
+}) => /*#__PURE__*/_jsx("div", {
+  ...getDataComponentAttribute('InsetBannerV3.Content'),
+  className: getClassName('bpk-inset-banner-v3__content'),
+  children: children
+});
+Content.displayName = 'BpkInsetBannerV3.Content';
+const TrailingAccessory = /*#__PURE__*/forwardRef((props, ref) => {
+  if ('onClick' in props && props.onClick) {
+    const {
+      'aria-label': ariaLabel,
+      children,
+      onClick,
+      ...rest
+    } = props;
+    return /*#__PURE__*/_jsx("button", {
+      ref: ref,
+      type: "button",
+      "aria-label": ariaLabel,
+      ...rest,
+      ...getDataComponentAttribute('InsetBannerV3.TrailingAccessory'),
+      className: getClassName('bpk-inset-banner-v3__trailing-accessory', 'bpk-inset-banner-v3__trailing-accessory--interactive'),
+      onClick: onClick,
+      children: children
+    });
+  }
+  const {
+    children,
+    ...rest
+  } = props;
+  return /*#__PURE__*/_jsx("div", {
+    ref: ref,
+    ...rest,
+    ...getDataComponentAttribute('InsetBannerV3.TrailingAccessory'),
+    className: getClassName('bpk-inset-banner-v3__trailing-accessory'),
+    children: children
+  });
+});
+TrailingAccessory.displayName = 'BpkInsetBannerV3.TrailingAccessory';
+const BpkInsetBannerV3 = {
+  Root,
+  Header,
+  LeadingAccessory,
+  Content,
+  Body,
+  TrailingAccessory
+};
+export default BpkInsetBannerV3;

package/bpk-component-inset-banner/src/BpkInsetBannerV3/BpkInsetBannerV3.module.css

@@ -0,0 +1,18 @@
+/*
+ * Backpack - Skyscanner's Design System
+ * 
+ * Copyright 2016 Skyscanner Ltd
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+.bpk-inset-banner-v3{border-radius:.5rem;overflow:hidden;container-type:inline-size}.bpk-inset-banner-v3--on-light{color:#161616;fill:#161616}.bpk-inset-banner-v3--on-dark{color:#fff;fill:#fff}.bpk-inset-banner-v3__header{display:grid;padding:.5rem 1rem;grid-template-columns:auto 1fr auto;grid-template-areas:"leading content trailing";align-items:center;gap:1rem}@container (max-width: 25rem){.bpk-inset-banner-v3__header{grid-template-columns:1fr auto;grid-template-areas:"leading trailing" "content content";gap:.25rem}.bpk-inset-banner-v3__header--horizontal{grid-template-columns:auto 1fr auto;grid-template-areas:"leading content trailing";align-items:center;gap:1rem}}.bpk-inset-banner-v3__header--vertical{grid-template-columns:1fr auto;grid-template-areas:"leading trailing" "content content";gap:.25rem}.bpk-inset-banner-v3__leading-accessory{display:flex;grid-area:leading;align-items:center}.bpk-inset-banner-v3__content{display:flex;min-width:0;grid-area:content;flex-direction:column;word-wrap:break-word}.bpk-inset-banner-v3__trailing-accessory{display:flex;grid-area:trailing;align-items:center}@container (max-width: 25rem){.bpk-inset-banner-v3__trailing-accessory{align-self:flex-start}}.bpk-inset-banner-v3__header--horizontal>.bpk-inset-banner-v3__trailing-accessory{align-self:center}.bpk-inset-banner-v3__trailing-accessory--interactive{padding:0;border:none;background:none;color:inherit;cursor:pointer;position:relative}.bpk-inset-banner-v3__trailing-accessory--interactive::before{position:absolute;top:calc(-2.75rem/2 + 50%);left:calc(-2.75rem/2 + 50%);content:"";width:2.75rem;height:2.75rem}.bpk-inset-banner-v3__trailing-accessory--interactive:focus-visible{outline:.125rem solid #0062e3;outline-offset:.125rem}.bpk-inset-banner-v3__body{padding:1rem}.bpk-inset-banner-v3__body--bleed{padding:0}

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

@@ -3,12 +3,17 @@ export interface BpkProviderProps {
     children: ReactNode;
 }
 /**
- * BpkProvider - Provides Chakra UI context for Backpack layout components
+ * BpkProvider - Provides context for Backpack layout and Ark-based components.
  *
- * Chakra UI 3.0 requires the `value` prop to be set to a system object.
- * We create a custom system with Backpack tokens using createSystem.
+ * Wraps children with:
+ * - Chakra UI system context (for layout components: BpkFlex, BpkGrid, etc.)
+ * - Ark UI LocaleProvider (for Ark-based components: BpkCheckboxV2, BpkSegmentedControlV2, etc.)
+ *
+ * RTL support: reads document direction reactively via MutationObserver and passes
+ * 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.
  *
  * @param {BpkProviderProps} props - The provider props.
- * @returns {JSX.Element} The provider wrapping its children with Chakra context.
+ * @returns {JSX.Element} The provider wrapping its children with Chakra and Ark context.
  */
 export declare const BpkProvider: ({ children }: BpkProviderProps) => JSX.Element;

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

@@ -16,6 +16,8 @@
  * limitations under the License.
  */
 
+import { useEffect, useState } from 'react';
+import { LocaleProvider } from '@ark-ui/react';
 import { ChakraProvider, createSystem, defaultConfig } from '@chakra-ui/react';
 import { createBpkConfig } from "./theme";
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -29,19 +31,96 @@ const {
   ...defaultConfigWithoutGlobalCss
 } = defaultConfig;
 const bpkSystem = createSystem(defaultConfigWithoutGlobalCss, createBpkConfig());
+// 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'.
+const FALLBACK_LOCALE_BY_DIRECTION = {
+  ltr: 'en-US',
+  rtl: 'ar-SA'
+};
+
+// Known RTL language subtags (ISO 639 codes). Used as fallback when
+// 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 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.
+const getLangDir = locale => {
+  try {
+    const dir = new Intl.Locale(locale).textInfo?.direction;
+    if (dir) return dir === 'rtl' ? 'rtl' : 'ltr';
+  } catch {
+    // Ignore invalid locale strings
+  }
+  return RTL_LANGUAGE_SUBTAGS.has(locale.split('-')[0].toLowerCase()) ? 'rtl' : 'ltr';
+};
+
+// Resolves the locale to pass to Ark's LocaleProvider.
+//
+// Priority rules:
+//   1. If html[dir] is explicitly set:
+//      - Use html[lang] only when 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'.
+//
+// SSR-safe: returns 'en-US' when document is unavailable.
+const getArkLocale = () => {
+  if (typeof document === 'undefined') return 'en-US';
+  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];
+  }
+  return lang || 'en-US';
+};
+
+// Reactive hook: subscribes to document.documentElement[dir] and [lang] changes
+// via MutationObserver. Re-renders BpkProvider when direction or locale is toggled
+// (e.g. Storybook RTL toolbar, runtime locale switcher).
+// SSR-safe: always initialises to 'en-US' so server and client agree on the first render,
+//           avoiding hydration mismatches. The real locale is read inside useEffect,
+//           which does not run on the server.
+const useArkLocale = () => {
+  const [locale, setLocale] = useState('en-US');
+  useEffect(() => {
+    setLocale(getArkLocale());
+    const observer = new MutationObserver(() => setLocale(getArkLocale()));
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['dir', 'lang']
+    });
+    return () => observer.disconnect();
+  }, []);
+  return locale;
+};
 
 /**
- * BpkProvider - Provides Chakra UI context for Backpack layout components
+ * BpkProvider - Provides context for Backpack layout and Ark-based components.
+ *
+ * Wraps children with:
+ * - Chakra UI system context (for layout components: BpkFlex, BpkGrid, etc.)
+ * - Ark UI LocaleProvider (for Ark-based components: BpkCheckboxV2, BpkSegmentedControlV2, etc.)
  *
- * Chakra UI 3.0 requires the `value` prop to be set to a system object.
- * We create a custom system with Backpack tokens using createSystem.
+ * RTL support: reads document direction reactively via MutationObserver and passes
+ * 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.
  *
  * @param {BpkProviderProps} props - The provider props.
- * @returns {JSX.Element} The provider wrapping its children with Chakra context.
+ * @returns {JSX.Element} The provider wrapping its children with Chakra and Ark context.
  */
 export const BpkProvider = ({
   children
-}) => /*#__PURE__*/_jsx(ChakraProvider, {
-  value: bpkSystem,
-  children: children
-});
+}) => {
+  const locale = useArkLocale();
+  return /*#__PURE__*/_jsx(ChakraProvider, {
+    value: bpkSystem,
+    children: /*#__PURE__*/_jsx(LocaleProvider, {
+      locale: locale,
+      children: children
+    })
+  });
+};

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

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+import type { HTMLAttributes, ReactNode } from 'react';
 import type StackOptionKeys from './BpkStack.constant';
 import type { BpkCommonLayoutProps } from './commonProps';
 import type { BpkSpacingValue, BpkResponsiveValue, BpkBasisValue } from './tokens';
@@ -144,7 +144,7 @@ export type VesselElement = 'div' | 'span' | 'section' | 'article' | 'nav' | 'ma
  */
 export type BpkVesselProps = {
     as?: VesselElement;
-} & React.HTMLAttributes<HTMLElement>;
+} & HTMLAttributes<HTMLElement>;
 /**
  * Component-specific props for BpkFlex
  * Includes all Flex props except those in BpkCommonLayoutProps

package/bpk-component-link/src/common-types.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithoutRef, ElementType, ReactNode, Ref } from 'react';
+import type { ComponentPropsWithoutRef, ElementType, JSX, ReactNode, Ref } from 'react';
 /**
  * Polymorphic component types following Chakra UI pattern.
  * Allows BpkLink to be rendered as different HTML elements while

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

@@ -1,9 +1,10 @@
 import BpkModal from './src/BpkModal';
 import { MODAL_STYLING } from './src/BpkModalInner';
 import { BpkModalV2 } from './src/BpkModalV2/BpkModal';
+import BpkModalV3 from './src/BpkModalV3/BpkModalV3';
 import { propTypes, defaultProps } from './src/legacy-prop-types';
 import themeAttributes from './src/themeAttributes';
 import type { Props } from './src/BpkModal';
 export type BpkModalProps = Props;
 export default BpkModal;
-export { propTypes, defaultProps, themeAttributes, BpkModalV2, MODAL_STYLING };
+export { propTypes, defaultProps, themeAttributes, BpkModalV2, BpkModalV3, MODAL_STYLING, };

package/bpk-component-modal/index.js

@@ -19,8 +19,9 @@
 import BpkModal from "./src/BpkModal";
 import { MODAL_STYLING } from "./src/BpkModalInner";
 import { BpkModalV2 } from "./src/BpkModalV2/BpkModal";
+import BpkModalV3 from "./src/BpkModalV3/BpkModalV3";
 // @ts-expect-error Untyped import. See `decisions/imports-ts-suppressions.md`.
 import { propTypes, defaultProps } from "./src/legacy-prop-types";
 import themeAttributes from "./src/themeAttributes";
 export default BpkModal;
-export { propTypes, defaultProps, themeAttributes, BpkModalV2, MODAL_STYLING };
+export { propTypes, defaultProps, themeAttributes, BpkModalV2, BpkModalV3, MODAL_STYLING };