@skyscanner/backpack-web 41.13.0 → 41.15.0

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

@@ -0,0 +1,86 @@
+import type { BpkSpacingValue, BpkSizeValue, BpkPositionValue, BpkResponsiveValue } from './tokens';
+/**
+ * Common spacing-related props shared by all Backpack layout components
+ * All spacing props must use Backpack spacing tokens or percentages
+ */
+export interface BpkSpacingProps {
+    padding?: BpkResponsiveValue<BpkSpacingValue>;
+    paddingTop?: BpkResponsiveValue<BpkSpacingValue>;
+    paddingRight?: BpkResponsiveValue<BpkSpacingValue>;
+    paddingBottom?: BpkResponsiveValue<BpkSpacingValue>;
+    paddingLeft?: BpkResponsiveValue<BpkSpacingValue>;
+    margin?: BpkResponsiveValue<BpkSpacingValue>;
+    marginTop?: BpkResponsiveValue<BpkSpacingValue>;
+    marginRight?: BpkResponsiveValue<BpkSpacingValue>;
+    marginBottom?: BpkResponsiveValue<BpkSpacingValue>;
+    marginLeft?: BpkResponsiveValue<BpkSpacingValue>;
+    marginStart?: BpkResponsiveValue<BpkSpacingValue>;
+    marginEnd?: BpkResponsiveValue<BpkSpacingValue>;
+    paddingStart?: BpkResponsiveValue<BpkSpacingValue>;
+    paddingEnd?: BpkResponsiveValue<BpkSpacingValue>;
+    marginInline?: BpkResponsiveValue<BpkSpacingValue>;
+    paddingInline?: BpkResponsiveValue<BpkSpacingValue>;
+    gap?: BpkResponsiveValue<BpkSpacingValue>;
+    width?: BpkResponsiveValue<BpkSizeValue>;
+    height?: BpkResponsiveValue<BpkSizeValue>;
+    minWidth?: BpkResponsiveValue<BpkSizeValue>;
+    minHeight?: BpkResponsiveValue<BpkSizeValue>;
+    maxWidth?: BpkResponsiveValue<BpkSizeValue>;
+    maxHeight?: BpkResponsiveValue<BpkSizeValue>;
+    top?: BpkResponsiveValue<BpkPositionValue>;
+    right?: BpkResponsiveValue<BpkPositionValue>;
+    bottom?: BpkResponsiveValue<BpkPositionValue>;
+    left?: BpkResponsiveValue<BpkPositionValue>;
+}
+/**
+ * Common props for all Backpack layout components
+ * Combines spacing and color props, and explicitly excludes className and
+ * certain props (e.g. typography, composite borders, transitions) to keep
+ * layout components purely structural.
+ *
+ * NOTE:
+ * - Layout components other than BpkBox do not expose event handlers.
+ * - BpkBox reintroduces a minimal set of events (onClick, onFocus, onBlur)
+ *   on its own props type.
+ */
+export interface BpkCommonLayoutProps extends BpkSpacingProps {
+    className?: never;
+    style?: never;
+    'data-testid'?: string;
+    'data-cy'?: string;
+    color?: never;
+    background?: never;
+    backgroundColor?: never;
+    borderColor?: never;
+    borderTopColor?: never;
+    borderRightColor?: never;
+    borderBottomColor?: never;
+    borderLeftColor?: never;
+    borderWidth?: never;
+    borderTopWidth?: never;
+    borderRightWidth?: never;
+    borderBottomWidth?: never;
+    borderLeftWidth?: never;
+    borderRadius?: never;
+    borderTopLeftRadius?: never;
+    borderTopRightRadius?: never;
+    borderBottomLeftRadius?: never;
+    borderBottomRightRadius?: never;
+    boxShadow?: never;
+    border?: never;
+    borderTop?: never;
+    borderRight?: never;
+    borderBottom?: never;
+    borderLeft?: never;
+    borderInline?: never;
+    borderBlock?: never;
+    borderX?: never;
+    borderY?: never;
+    transition?: never;
+    transitionProperty?: never;
+    transitionDuration?: never;
+    transitionTimingFunction?: never;
+    transitionDelay?: never;
+    transform?: never;
+    transformOrigin?: never;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,36 @@
+/**
+ * Exports spacing map for use in tokenUtils
+ * This allows tokenUtils to look up actual spacing values
+ *
+ * @returns {Record<string, string>} A map of spacing token names to values.
+ */
+export declare function getSpacingMap(): Record<string, string>;
+/**
+ * Gets the actual spacing value for a Backpack spacing token
+ *
+ * @param {string} token - Backpack spacing token name.
+ * @returns {string | undefined} The actual spacing value.
+ */
+export declare function getSpacingValue(token: string): string | undefined;
+/**
+ * Gets the actual border width value for a Backpack border size token
+ *
+ * @param {string} token - Backpack border size token name.
+ * @returns {string | undefined} The actual border width value.
+ */
+export declare function getBorderSizeValue(token: string): string | undefined;
+/**
+ * Gets the actual border radius value for a Backpack border radius token
+ *
+ * @param {string} token - Backpack border radius token name.
+ * @returns {string | undefined} The actual border radius value.
+ */
+export declare function getBorderRadiusValue(token: string): string | undefined;
+/**
+ * Gets the actual box-shadow value for a Backpack shadow token
+ *
+ * @param {string} token - Backpack shadow token name.
+ * @returns {string | undefined} The actual box-shadow value.
+ */
+export declare function getShadowValue(token: string): string | undefined;
+export declare function createBpkConfig(): import("@chakra-ui/react").SystemConfig;

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

@@ -0,0 +1,229 @@
+/*
+ * 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 { defineConfig } from '@chakra-ui/react';
+// Import tokens from Backpack foundations
+// Note: Some tokens may not be in TypeScript definitions but exist at runtime
+
+const bpkTokens = require('@skyscanner/bpk-foundations-web/tokens/base.es6');
+
+// NOTE:
+// We intentionally do not use the raw breakpoint *values* from foundations here.
+// Foundations exports breakpoint values such as `breakpointMobile = "32rem"` which
+// are used primarily for max-width queries (e.g. `(max-width: 32rem)`).
+//
+// Backpack layout responsive values in this package are mobile-first and behave
+// like Chakra breakpoints (min-width thresholds). To align with Backpack’s
+// intended breakpoint ranges we define lower-bound (min-width) thresholds:
+//
+// - small-mobile: 320px+
+// - mobile: 360px+
+// - small-tablet: 513px+
+// - tablet: 769px+
+// - desktop: 1025px+
+
+// Note: Spacing tokens are defined as SCSS functions in Backpack foundations,
+// not as direct values. We need to use the actual rem values from the SCSS functions.
+// Based on @skyscanner/bpk-foundations-web/tokens/base.default.scss:
+// - bpk-spacing-sm() returns .25rem
+// - bpk-spacing-md() returns .5rem
+// - bpk-spacing-lg() returns 1.5rem
+// - bpk-spacing-xl() returns 2rem (needs verification)
+// - bpk-spacing-xxl() returns 2.5rem
+// - bpk-spacing-base() returns 1rem (standard base spacing)
+// TODO: CLOV-1021 - will add spacing tokens to Backpack Foundations package and use them here after we ship the PoC
+const spacingXs = '.125rem'; // 2px
+const spacingSm = '.25rem';
+const spacingBase = '1rem'; // Standard base spacing
+const spacingMd = '.5rem';
+const spacingLg = '1.5rem';
+const spacingXl = '2rem';
+const spacingXxl = '2.5rem';
+
+/**
+ * Backpack Theme Configuration for Chakra UI
+ *
+ * This theme maps Backpack design tokens from @skyscanner/bpk-foundations-web
+ * to Chakra UI's theme structure.
+ */
+
+/**
+ * Maps Backpack spacing tokens to actual rem values.
+ * These come directly from @skyscanner/bpk-foundations-web.
+ */
+// Spacing tokens - directly imported from foundations
+const spacingMap = {
+  'bpk-spacing-none': {
+    value: '0'
+  },
+  // Temporary: Foundations does not yet export a 2px spacing token. This will be
+  // replaced with a foundations value once available.
+  'bpk-spacing-xs': {
+    value: spacingXs
+  },
+  'bpk-spacing-sm': {
+    value: spacingSm
+  },
+  'bpk-spacing-base': {
+    value: spacingBase
+  },
+  'bpk-spacing-md': {
+    value: spacingMd
+  },
+  'bpk-spacing-lg': {
+    value: spacingLg
+  },
+  'bpk-spacing-xl': {
+    value: spacingXl
+  },
+  'bpk-spacing-xxl': {
+    value: spacingXxl
+  }
+};
+
+/**
+ * Maps Backpack border size tokens to actual border width values
+ * These come directly from @skyscanner/bpk-foundations-web
+ */
+const borderSizeMap = {
+  'bpk-border-size-sm': bpkTokens.borderSizeSm,
+  'bpk-border-size-lg': bpkTokens.borderSizeLg,
+  'bpk-border-size-xl': bpkTokens.borderSizeXl
+};
+
+/**
+ * Maps Backpack border radius tokens to actual radius values.
+ * These come directly from @skyscanner/bpk-foundations-web.
+ */
+const borderRadiusMap = {
+  'bpk-border-radius-none': '0',
+  'bpk-border-radius-xs': bpkTokens.borderRadiusXs,
+  'bpk-border-radius-sm': bpkTokens.borderRadiusSm,
+  'bpk-border-radius-md': bpkTokens.borderRadiusMd,
+  'bpk-border-radius-lg': bpkTokens.borderRadiusLg,
+  'bpk-border-radius-xl': bpkTokens.borderRadiusXl,
+  'bpk-border-radius-full': bpkTokens.borderRadiusFull
+};
+
+/**
+ * Maps Backpack shadow tokens to actual box-shadow values
+ * These come directly from @skyscanner/bpk-foundations-web
+ */
+const shadowMap = {
+  'bpk-shadow-sm': bpkTokens.boxShadowSm,
+  'bpk-shadow-lg': bpkTokens.boxShadowLg,
+  'bpk-shadow-xl': bpkTokens.boxShadowXl
+};
+
+/**
+ * Chakra expects raw width values (e.g. "48rem"), not full media queries.
+ * The media query construction is handled internally by Chakra's system.
+ *
+ * We align Backpack breakpoint tokens to Chakra's keys like this:
+ * - base: 0 (implicit)
+ * - sm: small-mobile (>= 320px)
+ * - md: mobile (>= 360px)
+ * - lg: small-tablet (>= 513px)
+ * - xl: tablet (>= 769px)
+ * - 2xl: desktop (>= 1025px)
+ */
+// TODO: CLOV-1021 - will add breakpoint boundary tokens to Backpack Foundations package and use them here after we ship the PoC
+const breakpointMap = {
+  base: '0rem',
+  sm: '20rem',
+  // 320px
+  md: '22.5rem',
+  // 360px
+  lg: '32.0625rem',
+  // 513px
+  xl: '48.0625rem',
+  // 769px
+  '2xl': '64.0625rem' // 1025px
+};
+
+/**
+ * Exports spacing map for use in tokenUtils
+ * This allows tokenUtils to look up actual spacing values
+ *
+ * @returns {Record<string, string>} A map of spacing token names to values.
+ */
+export function getSpacingMap() {
+  // Return simple string values for backward compatibility with utilities
+  const simpleMap = {};
+  Object.entries(spacingMap).forEach(([key, obj]) => {
+    simpleMap[key] = obj.value;
+  });
+  return simpleMap;
+}
+
+/**
+ * Gets the actual spacing value for a Backpack spacing token
+ *
+ * @param {string} token - Backpack spacing token name.
+ * @returns {string | undefined} The actual spacing value.
+ */
+export function getSpacingValue(token) {
+  return spacingMap[token]?.value;
+}
+
+/**
+ * Gets the actual border width value for a Backpack border size token
+ *
+ * @param {string} token - Backpack border size token name.
+ * @returns {string | undefined} The actual border width value.
+ */
+export function getBorderSizeValue(token) {
+  return borderSizeMap[token];
+}
+
+/**
+ * Gets the actual border radius value for a Backpack border radius token
+ *
+ * @param {string} token - Backpack border radius token name.
+ * @returns {string | undefined} The actual border radius value.
+ */
+export function getBorderRadiusValue(token) {
+  return borderRadiusMap[token];
+}
+
+/**
+ * Gets the actual box-shadow value for a Backpack shadow token
+ *
+ * @param {string} token - Backpack shadow token name.
+ * @returns {string | undefined} The actual box-shadow value.
+ */
+export function getShadowValue(token) {
+  return shadowMap[token];
+}
+export function createBpkConfig() {
+  // Convert breakpoint map to Chakra UI format
+  // Breakpoints in Chakra v3 are typically simple strings in the breakpoints object
+  const chakraBreakpoints = {};
+  Object.entries(breakpointMap).forEach(([token, value]) => {
+    chakraBreakpoints[token] = value;
+  });
+  return defineConfig({
+    cssVarsPrefix: 'bpk',
+    theme: {
+      tokens: {
+        spacing: spacingMap
+      },
+      breakpoints: chakraBreakpoints
+    }
+  });
+}

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

@@ -0,0 +1,108 @@
+export type BpkLayoutComponentName = 'BpkBox' | 'BpkFlex' | 'BpkGrid' | 'BpkStack';
+/**
+ * Allowlisted, component-scoped prop groups that are eligible for Backpack responsive value
+ * processing (Backpack breakpoint keys -> Chakra breakpoint keys).
+ *
+ * NOTE:
+ * - Spacing/size/position props are processed separately via `processBpkProps` and therefore
+ *   are intentionally NOT included here.
+ * - These groups are meant to keep the responsive surface predictable per component, while
+ *   avoiding duplicated per-component breakpoint mapping logic.
+ */
+type BpkResponsivePropGroups = {
+    /**
+     * Container-level layout props (how children are laid out).
+     */
+    container: readonly string[];
+    /**
+     * Item-level layout props (how this element participates in a parent layout).
+     */
+    item?: readonly string[];
+};
+export declare const BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT: Record<BpkLayoutComponentName, BpkResponsivePropGroups>;
+export declare const BPK_RESPONSIVE_PROP_KEYS_BY_COMPONENT: Record<BpkLayoutComponentName, readonly string[]>;
+export type ProcessBpkComponentPropsOptions = {
+    component: BpkLayoutComponentName;
+    /**
+     * Optional map of responsive props. When provided, it will be filtered to the
+     * allowlist for the given component, then breakpoint-normalised.
+     *
+     * This is useful for components like `BpkFlex` and `BpkGrid` that expose a
+     * public API with different prop names.
+     */
+    responsiveProps?: Record<string, any>;
+    /**
+     * Optional mapping of source prop name -> target prop name.
+     * Primarily kept for parity with `processResponsiveProps`.
+     */
+    propNameMap?: Record<string, string>;
+};
+/**
+ * Process a component's props in one place:
+ * - strip className/style
+ * - process spacing/size/position props (including breakpoint mapping + token conversion)
+ * - process allowlisted non-spacing responsive layout props (breakpoint mapping only)
+ *
+ * The allowlist is grouped by component via `BPK_RESPONSIVE_PROP_KEYS_BY_COMPONENT`.
+ *
+ * @param {T} props - The component props to process.
+ * @param {ProcessBpkComponentPropsOptions} options - Component processing options (allowlist group + mapping).
+ * @returns {Record<string, any>} The processed props ready to pass to Chakra primitives.
+ */
+export declare function processBpkComponentProps<T extends Record<string, any>>(props: T, options: ProcessBpkComponentPropsOptions): Record<string, any>;
+/**
+ * Converts Backpack spacing token to Chakra UI compatible value
+ * Returns the actual spacing value from the theme, not a token path
+ *
+ * @param {string} value - Backpack spacing token (e.g., 'bpk-spacing-base') or percentage
+ * @returns {string} The actual spacing value in rem or the percentage string
+ */
+export declare function convertBpkSpacingToChakra(value: string): string;
+/**
+ * Recursively processes responsive values (arrays or objects) to validate and convert tokens
+ *
+ * @param {*} value - The value to process (could be string, array, or object)
+ * @param {Function} converter - Function to convert valid tokens to actual values
+ * @param {Function} validator - Function to validate if a token is allowed
+ * @param {string} propName - The name of the prop being processed (for warning messages)
+ * @returns {*} The processed value with tokens converted, or undefined for invalid tokens
+ */
+export declare function normalizeResponsiveObject<T>(value: Record<string, T>): Record<string, T>;
+export declare function processResponsiveValue(value: any, converter: (v: string) => string, validator: (v: string) => boolean, propName: string): any;
+/**
+ * Validates and converts spacing props for Chakra UI
+ * Handles all spacing-related properties including padding, margin, gap, size, border radius and position
+ *
+ * @param {T} props - Component props object
+ * @returns {Record<string, any>} Processed props with spacing tokens converted to actual values
+ */
+export declare function processSpacingProps<T extends Record<string, any>>(props: T): Record<string, any>;
+/**
+ * Processes all props to convert Backpack tokens to Chakra UI format
+ * Also explicitly removes className and style to prevent ad-hoc overrides
+ *
+ * Processing order:
+ * 1. Remove className & style
+ * 2. Process spacing props (includes position)
+ *
+ * @param {T} props - Component props object
+ * @returns {Record<string, any>} Processed props with tokens converted and disallowed props removed
+ */
+export declare function processBpkProps<T extends Record<string, any>>(props: T): Record<string, any>;
+/**
+ * Processes responsive props that are simple string/enum values (non-spacing)
+ * using Backpack breakpoint keys. Array syntax is rejected as in spacing.
+ *
+ * @param {*} value - The value to process
+ * @param {string} propName - The name of the prop being processed
+ * @returns {*} The processed value with breakpoint keys mapped to Chakra keys
+ */
+export declare function processResponsiveStringProp(value: any, propName: string): any;
+/**
+ * Processes a collection of responsive props.
+ * @param {Record<string, any>} props - Object containing prop values.
+ * @param {Record<string, string>} propNameMap - Map of prop name to CSS/Chakra property name (for error messages and mapping).
+ * @returns {Record<string, any>} Processed props object.
+ */
+export declare function processResponsiveProps(props: Record<string, any>, propNameMap?: Record<string, string>): Record<string, any>;
+export {};