@skyscanner/backpack-web 41.13.0 → 41.15.0

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

@@ -0,0 +1,323 @@
+/*
+ * 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 StackOptionKeys from "./BpkStack.constant";
+import { getSpacingValue } from "./theme";
+import { BpkBreakpointToChakraKey, isValidSpacingValue, isValidSizeValue, isValidPositionValue, isPercentage } from "./tokens";
+
+/**
+ * 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.
+ */
+
+export const BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT = {
+  BpkBox: {
+    container: [
+    // Display
+    'display',
+    // Flex container props
+    'flexDirection', 'flexWrap', 'justifyContent', 'alignItems', 'alignContent',
+    // Grid container props
+    'gridTemplateColumns', 'gridTemplateRows', 'gridTemplateAreas', 'gridAutoFlow', 'gridAutoRows', 'gridAutoColumns'],
+    item: [
+    // Flex item props
+    'flex', 'flexGrow', 'flexShrink', 'flexBasis', 'order', 'alignSelf', 'justifySelf',
+    // Grid item placement props (useful on Box when composing grids)
+    'gridColumn', 'gridRow']
+  },
+  // Note: BpkFlex maps its public API props to these Chakra keys.
+  BpkFlex: {
+    container: ['flexDirection', 'justifyContent', 'alignItems', 'flexWrap'],
+    item: ['flexGrow', 'flexShrink', 'flexBasis']
+  },
+  // Note: BpkGrid maps its public API props to these Chakra keys.
+  BpkGrid: {
+    container: ['justifyContent', 'alignItems', 'gridTemplateColumns', 'gridTemplateRows', 'gridTemplateAreas', 'gridAutoFlow', 'gridAutoRows', 'gridAutoColumns'],
+    item: [
+    // Used when placing the grid itself within a parent grid.
+    'gridColumn', 'gridRow']
+  },
+  // Note: BpkStack uses Chakra Stack option prop names directly.
+  BpkStack: {
+    container: StackOptionKeys
+  }
+};
+export const BPK_RESPONSIVE_PROP_KEYS_BY_COMPONENT = {
+  BpkBox: [...BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkBox.container, ...(BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkBox.item ?? [])],
+  BpkFlex: [...BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkFlex.container, ...(BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkFlex.item ?? [])],
+  BpkGrid: [...BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkGrid.container, ...(BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkGrid.item ?? [])],
+  BpkStack: [...BPK_RESPONSIVE_PROP_GROUPS_BY_COMPONENT.BpkStack.container]
+};
+function filterToAllowlist(props, allowlist) {
+  const allowed = new Set(allowlist);
+  const result = {};
+  Object.keys(props).forEach(key => {
+    if (allowed.has(key) && props[key] !== undefined) {
+      result[key] = props[key];
+    }
+  });
+  return result;
+}
+
+/**
+ * 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 function processBpkComponentProps(props, options) {
+  const processed = processBpkProps(props);
+  const allowlist = BPK_RESPONSIVE_PROP_KEYS_BY_COMPONENT[options.component];
+  const responsiveSource = options.responsiveProps ? filterToAllowlist(options.responsiveProps, allowlist) : filterToAllowlist(processed, allowlist);
+  if (Object.keys(responsiveSource).length === 0) {
+    return processed;
+  }
+
+  // Ensure allowlisted layout props do NOT fall through unprocessed (e.g. array responsive values).
+  // These props must be provided via the responsive processing pipeline only.
+  const cleanedProcessed = {
+    ...processed
+  };
+  allowlist.forEach(key => {
+    if (key in cleanedProcessed) {
+      delete cleanedProcessed[key];
+    }
+  });
+  const responsiveProcessed = processResponsiveProps(responsiveSource, options.propNameMap);
+
+  // Remove keys that ended up as `undefined` (e.g. array responsive values are rejected).
+  Object.keys(responsiveProcessed).forEach(key => {
+    if (responsiveProcessed[key] === undefined) {
+      delete responsiveProcessed[key];
+    }
+  });
+  return {
+    ...cleanedProcessed,
+    ...responsiveProcessed
+  };
+}
+
+/**
+ * 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 function convertBpkSpacingToChakra(value) {
+  if (isPercentage(value)) {
+    return value; // Percentages pass through
+  }
+
+  // Look up the actual spacing value from the theme
+  const spacingValue = getSpacingValue(value);
+  if (spacingValue !== undefined) {
+    return spacingValue;
+  }
+
+  // Fallback: if token not found, return the value as-is (will cause a warning)
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line no-console
+    console.warn(`Spacing token "${value}" not found in theme. Returning as-is.`);
+  }
+  return value;
+}
+
+/**
+ * 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 function normalizeResponsiveObject(value) {
+  const normalized = {};
+  Object.entries(value).forEach(([key, val]) => {
+    if (key === 'base') {
+      normalized.base = val;
+      return;
+    }
+    const chakraKey = BpkBreakpointToChakraKey[key];
+    if (chakraKey) {
+      normalized[chakraKey] = val;
+    } else if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.warn(`Unknown breakpoint "${key}" used in responsive prop. ` + 'Use Backpack breakpoint tokens such as mobile, tablet or desktop.');
+    }
+  });
+  return normalized;
+}
+export function processResponsiveValue(value, converter, validator, propName) {
+  if (value === undefined || value === null) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.warn(`Array-based responsive values are not supported for prop "${propName}". ` + `Please use Backpack breakpoint keys instead.`);
+    }
+    return undefined;
+  }
+  if (typeof value === 'object') {
+    const normalized = normalizeResponsiveObject(value);
+    const result = {};
+    Object.keys(normalized).forEach(key => {
+      const processedValue = processResponsiveValue(normalized[key], converter, validator, propName);
+      if (processedValue !== undefined) {
+        result[key] = processedValue;
+      }
+    });
+    return Object.keys(result).length > 0 ? result : undefined;
+  }
+  const strValue = String(value);
+  if (!validator(strValue)) {
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.warn(`Invalid value "${strValue}" for prop "${propName}". ` + `Only Backpack tokens are allowed.`);
+    }
+    return undefined; // Invalid values are removed
+  }
+  return converter(strValue);
+}
+
+/**
+ * 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 function processSpacingProps(props) {
+  const spacingKeys = [
+  // Padding props
+  'padding', 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft', 'paddingStart', 'paddingEnd', 'paddingInline',
+  // Margin props
+  'margin', 'marginTop', 'marginRight', 'marginBottom', 'marginLeft', 'marginStart', 'marginEnd', 'marginInline',
+  // Gap and spacing
+  'gap', 'spacing', 'rowGap', 'columnGap',
+  // Size props
+  'width', 'height', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight',
+  // Position props
+  'top', 'right', 'bottom', 'left'];
+  const processed = {
+    ...props
+  };
+  const sizeKeys = ['width', 'height', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight'];
+  const positionKeys = ['top', 'right', 'bottom', 'left'];
+  spacingKeys.forEach(key => {
+    if (key in processed && processed[key] !== undefined) {
+      const isSizeProp = sizeKeys.includes(key);
+      const isPositionProp = positionKeys.includes(key);
+      let converter;
+      if (isSizeProp || isPositionProp) {
+        converter = v => v;
+      } else {
+        converter = convertBpkSpacingToChakra;
+      }
+      let validator;
+      if (isSizeProp) {
+        validator = isValidSizeValue;
+      } else if (isPositionProp) {
+        validator = isValidPositionValue;
+      } else {
+        validator = isValidSpacingValue;
+      }
+      const processedValue = processResponsiveValue(processed[key], converter, validator, key);
+      if (processedValue !== undefined) {
+        processed[key] = processedValue;
+      } else {
+        delete processed[key];
+      }
+    }
+  });
+  return processed;
+}
+
+/**
+ * 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 function processBpkProps(props) {
+  // Explicitly remove className and style to prevent style overrides
+  const {
+    className,
+    style,
+    ...cleanProps
+  } = props;
+  if (className !== undefined && process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line no-console
+    console.warn('className prop is not allowed on Backpack layout components. ' + 'It has been removed to maintain design system consistency.');
+  }
+  if (style !== undefined && process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line no-console
+    console.warn('style prop is not allowed on Backpack layout components. ' + 'It has been removed to maintain design system consistency.');
+  }
+
+  // Process spacing props (includes position)
+  return processSpacingProps(cleanProps);
+}
+
+/**
+ * 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 function processResponsiveStringProp(value, propName) {
+  return processResponsiveValue(value, v => v, () => true, propName);
+}
+
+/**
+ * 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 function processResponsiveProps(props, propNameMap) {
+  const processed = {};
+  Object.keys(props).forEach(key => {
+    if (props[key] !== undefined) {
+      const targetPropName = propNameMap ? propNameMap[key] || key : key;
+      processed[targetPropName] = processResponsiveStringProp(props[key], targetPropName);
+    }
+  });
+  return processed;
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Backpack Design Tokens for Layout Components
+ *
+ * This file provides token mappings from Backpack design tokens to Chakra UI theme.
+ * All tokens are sourced from @skyscanner/bpk-foundations-web
+ */
+/**
+ * Backpack Spacing Tokens
+ * Use these constants to ensure type safety when passing spacing props
+ */
+export declare const BpkSpacing: {
+    readonly None: "bpk-spacing-none";
+    readonly XS: "bpk-spacing-xs";
+    readonly SM: "bpk-spacing-sm";
+    readonly Base: "bpk-spacing-base";
+    readonly MD: "bpk-spacing-md";
+    readonly LG: "bpk-spacing-lg";
+    readonly XL: "bpk-spacing-xl";
+    readonly XXL: "bpk-spacing-xxl";
+};
+export type BpkSpacingToken = typeof BpkSpacing[keyof typeof BpkSpacing];
+/**
+ * Backpack Breakpoint Tokens
+ * Use these constants to ensure type safety when defining responsive overrides
+ * These map to the simplified keys defined in the Chakra theme
+ */
+export declare const BpkBreakpoint: {
+    readonly SmallMobile: "small-mobile";
+    readonly Mobile: "mobile";
+    readonly SmallTablet: "small-tablet";
+    readonly Tablet: "tablet";
+    readonly Desktop: "desktop";
+};
+export type BpkBreakpointToken = typeof BpkBreakpoint[keyof typeof BpkBreakpoint];
+export type ChakraBreakpointKey = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export declare const BpkBreakpointToChakraKey: Record<BpkBreakpointToken, ChakraBreakpointKey>;
+/**
+ * Helper type for values that can be Backpack tokens or percentages
+ * but NOT px/rem values
+ */
+export type BpkSpacingValue = BpkSpacingToken | `${number}%`;
+export type BpkBreakpointValue = BpkBreakpointToken;
+/**
+ * Helper type for size props that can use rem, percentages or semantic values.
+ * This is intentionally separate from BpkSpacingValue to avoid encouraging
+ * spacing tokens for explicit sizes.
+ */
+export type BpkSizeValue = `${number}rem` | `${number}%` | 'auto' | 'full' | 'fit-content';
+/**
+ * Helper type for position props that can use rem or percentages.
+ * We intentionally do not allow semantic values like 'auto' here.
+ */
+export type BpkPositionValue = `${number}rem` | `${number}%`;
+/**
+ * Helper type for flex-basis prop that can use rem, percentages or semantic values.
+ * Excludes 'px' values to enforce design system constraints.
+ */
+export type BpkBasisValue = `${number}rem` | `${number}%` | 'auto' | 'content' | 'fit-content' | 'max-content' | 'min-content' | 'initial' | 'inherit';
+/**
+ * Helper type for responsive values based on Backpack breakpoints.
+ *
+ * We intentionally only support:
+ * - a single scalar value (non-responsive)
+ * - an object keyed by Backpack breakpoint tokens (and optional base)
+ *
+ * We do NOT support array-based responsive values in the public API.
+ */
+export type BpkResponsiveValue<T> = T | Partial<Record<BpkBreakpointToken | 'base', T>>;
+/**
+ * Validates if a value is a percentage string
+ *
+ * @param {string} value - The value to validate
+ * @returns {boolean} True if the value is a valid percentage string
+ */
+export declare function isPercentage(value: string): boolean;
+/**
+ * Validates if a spacing value is valid (token or percentage)
+ *
+ * @param {string} value - The spacing value to validate
+ * @returns {boolean} True if the value is a valid Backpack spacing token or percentage
+ */
+export declare function isValidSpacingValue(value: string): boolean;
+/**
+ * Validates if a size value is valid
+ *
+ * @param {string} value - The size value to validate
+ * @returns {boolean} True if the value is a valid rem/percentage/semantic size
+ */
+export declare function isValidSizeValue(value: string): boolean;
+/**
+ * Validates if a position value is valid
+ *
+ * @param {string} value - The position value to validate
+ * @returns {boolean} True if the value is a valid rem or percentage
+ */
+export declare function isValidPositionValue(value: string): boolean;

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

@@ -0,0 +1,138 @@
+/*
+ * 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.
+ */
+
+/**
+ * Backpack Design Tokens for Layout Components
+ *
+ * This file provides token mappings from Backpack design tokens to Chakra UI theme.
+ * All tokens are sourced from @skyscanner/bpk-foundations-web
+ */
+
+/**
+ * Backpack Spacing Tokens
+ * Use these constants to ensure type safety when passing spacing props
+ */
+export const BpkSpacing = {
+  None: 'bpk-spacing-none',
+  XS: 'bpk-spacing-xs',
+  SM: 'bpk-spacing-sm',
+  Base: 'bpk-spacing-base',
+  MD: 'bpk-spacing-md',
+  LG: 'bpk-spacing-lg',
+  XL: 'bpk-spacing-xl',
+  XXL: 'bpk-spacing-xxl'
+};
+/**
+ * Backpack Breakpoint Tokens
+ * Use these constants to ensure type safety when defining responsive overrides
+ * These map to the simplified keys defined in the Chakra theme
+ */
+export const BpkBreakpoint = {
+  SmallMobile: 'small-mobile',
+  Mobile: 'mobile',
+  SmallTablet: 'small-tablet',
+  Tablet: 'tablet',
+  Desktop: 'desktop'
+};
+export const BpkBreakpointToChakraKey = {
+  // Keep this mapping in sync with the breakpoints configured in `theme.ts`.
+  // `base` is reserved for "default value" and is not a breakpoint token.
+  'small-mobile': 'sm',
+  mobile: 'md',
+  'small-tablet': 'lg',
+  tablet: 'xl',
+  desktop: '2xl'
+};
+
+/**
+ * Helper type for values that can be Backpack tokens or percentages
+ * but NOT px/rem values
+ */
+
+/**
+ * Helper type for size props that can use rem, percentages or semantic values.
+ * This is intentionally separate from BpkSpacingValue to avoid encouraging
+ * spacing tokens for explicit sizes.
+ */
+
+/**
+ * Helper type for position props that can use rem or percentages.
+ * We intentionally do not allow semantic values like 'auto' here.
+ */
+
+/**
+ * Helper type for flex-basis prop that can use rem, percentages or semantic values.
+ * Excludes 'px' values to enforce design system constraints.
+ */
+
+/**
+ * Helper type for responsive values based on Backpack breakpoints.
+ *
+ * We intentionally only support:
+ * - a single scalar value (non-responsive)
+ * - an object keyed by Backpack breakpoint tokens (and optional base)
+ *
+ * We do NOT support array-based responsive values in the public API.
+ */
+
+/**
+ * Validates if a value is a percentage string
+ *
+ * @param {string} value - The value to validate
+ * @returns {boolean} True if the value is a valid percentage string
+ */
+export function isPercentage(value) {
+  return /^\d+(\.\d+)?%$/.test(value);
+}
+
+/**
+ * Validates if a spacing value is valid (token or percentage)
+ *
+ * @param {string} value - The spacing value to validate
+ * @returns {boolean} True if the value is a valid Backpack spacing token or percentage
+ */
+export function isValidSpacingValue(value) {
+  return Object.values(BpkSpacing).includes(value) || isPercentage(value);
+}
+
+/**
+ * Validates if a size value is valid
+ *
+ * @param {string} value - The size value to validate
+ * @returns {boolean} True if the value is a valid rem/percentage/semantic size
+ */
+export function isValidSizeValue(value) {
+  return /^-?\d+(\.\d+)?rem$/.test(value) ||
+  // rem values
+  isPercentage(value) ||
+  // percentage values
+  value === 'auto' || value === 'full' || value === 'fit-content';
+}
+
+/**
+ * Validates if a position value is valid
+ *
+ * @param {string} value - The position value to validate
+ * @returns {boolean} True if the value is a valid rem or percentage
+ */
+export function isValidPositionValue(value) {
+  return /^-?\d+(\.\d+)?rem$/.test(value) ||
+  // rem values
+  isPercentage(value) // percentage values
+  ;
+}