@skyscanner/backpack-web 41.6.0 → 41.7.0-beta-v1

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
+  ;
+}

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

@@ -0,0 +1,194 @@
+import type { ReactNode } from 'react';
+import type StackOptionKeys from './BpkStack.constant';
+import type { BpkCommonLayoutProps } from './commonProps';
+import type { BpkSpacingValue, BpkResponsiveValue, BpkBasisValue } from './tokens';
+import type { BoxProps, FlexProps, GridProps, GridItemProps, StackProps } from '@chakra-ui/react';
+/**
+ * Layout-level event props that should not be exposed on layout components
+ * by default. BpkBox will reintroduce a minimal subset (onClick, onFocus,
+ * onBlur) explicitly on its own props type.
+ */
+type LayoutEventProps = 'onClick' | 'onMouseEnter' | 'onMouseLeave' | 'onMouseOver' | 'onMouseOut' | 'onMouseDown' | 'onMouseUp' | 'onFocus' | 'onBlur' | 'onKeyDown' | 'onKeyUp' | 'onKeyPress';
+/**
+ * Shorthand props from the underlying layout system that we do NOT expose on
+ * Backpack layout components. These mostly mirror longer-form spacing,
+ * sizing and visual props that we already model explicitly via
+ * BpkCommonLayoutProps and BpkFlexGridProps.
+ */
+type DisallowedShorthandProps = 'p' | 'pt' | 'pr' | 'pb' | 'pl' | 'px' | 'py' | 'm' | 'mt' | 'mr' | 'mb' | 'ml' | 'mx' | 'my' | 'w' | 'h' | 'minW' | 'maxW' | 'minH' | 'maxH' | 'bg' | 'rounded' | 'shadow';
+/**
+ * Flexbox & grid layout props that we explicitly support on Backpack layout
+ * components. These are a curated subset of the underlying Box flex/grid API
+ * that are useful for structural layout.
+ */
+export interface BpkFlexGridProps {
+    display?: BoxProps['display'];
+    flexDirection?: BoxProps['flexDirection'];
+    flexWrap?: BoxProps['flexWrap'];
+    justifyContent?: BoxProps['justifyContent'];
+    alignItems?: BoxProps['alignItems'];
+    alignContent?: BoxProps['alignContent'];
+    flex?: BoxProps['flex'];
+    flexGrow?: BoxProps['flexGrow'];
+    flexShrink?: BoxProps['flexShrink'];
+    flexBasis?: BoxProps['flexBasis'];
+    order?: BoxProps['order'];
+    alignSelf?: BoxProps['alignSelf'];
+    justifySelf?: BoxProps['justifySelf'];
+    gridTemplateColumns?: BoxProps['gridTemplateColumns'];
+    gridTemplateRows?: BoxProps['gridTemplateRows'];
+    gridTemplateAreas?: BoxProps['gridTemplateAreas'];
+    gridAutoFlow?: BoxProps['gridAutoFlow'];
+    gridAutoRows?: BoxProps['gridAutoRows'];
+    gridAutoColumns?: BoxProps['gridAutoColumns'];
+    rowGap?: BoxProps['rowGap'];
+    columnGap?: BoxProps['columnGap'];
+}
+export type FlexGridPropKeys = keyof BpkFlexGridProps;
+/**
+ * Curated subset of Box layout props that support Backpack responsive values.
+ *
+ * NOTE:
+ * - These are structural layout props (flex/grid/display) that we want to allow
+ *   on `BpkBox`, but using Backpack breakpoint keys rather than Chakra's
+ *   array syntax or Chakra breakpoint keys.
+ * - Spacing/size/position props are handled separately via `BpkCommonLayoutProps`.
+ */
+type BpkBoxResponsiveLayoutProps = {
+    display?: BpkResponsiveValue<BoxProps['display']>;
+    flexDirection?: BpkResponsiveValue<BoxProps['flexDirection']>;
+    flexWrap?: BpkResponsiveValue<BoxProps['flexWrap']>;
+    justifyContent?: BpkResponsiveValue<BoxProps['justifyContent']>;
+    alignItems?: BpkResponsiveValue<BoxProps['alignItems']>;
+    alignContent?: BpkResponsiveValue<BoxProps['alignContent']>;
+    flex?: BpkResponsiveValue<BoxProps['flex']>;
+    flexGrow?: BpkResponsiveValue<BoxProps['flexGrow']>;
+    flexShrink?: BpkResponsiveValue<BoxProps['flexShrink']>;
+    flexBasis?: BpkResponsiveValue<BoxProps['flexBasis']>;
+    order?: BpkResponsiveValue<BoxProps['order']>;
+    alignSelf?: BpkResponsiveValue<BoxProps['alignSelf']>;
+    justifySelf?: BpkResponsiveValue<BoxProps['justifySelf']>;
+    gridTemplateColumns?: BpkResponsiveValue<BoxProps['gridTemplateColumns']>;
+    gridTemplateRows?: BpkResponsiveValue<BoxProps['gridTemplateRows']>;
+    gridTemplateAreas?: BpkResponsiveValue<BoxProps['gridTemplateAreas']>;
+    gridAutoFlow?: BpkResponsiveValue<BoxProps['gridAutoFlow']>;
+    gridAutoRows?: BpkResponsiveValue<BoxProps['gridAutoRows']>;
+    gridAutoColumns?: BpkResponsiveValue<BoxProps['gridAutoColumns']>;
+    gridColumn?: BpkResponsiveValue<BoxProps['gridColumn']>;
+    gridRow?: BpkResponsiveValue<BoxProps['gridRow']>;
+};
+type BpkBoxResponsiveLayoutPropKeys = keyof BpkBoxResponsiveLayoutProps;
+/**
+ * Base type that removes common layout props, reserved props (className,
+ * children) and all layout-level event props from Chakra UI props.
+ *
+ * These will be replaced with Backpack-specific types.
+ */
+export type RemoveCommonProps<T> = Omit<T, keyof BpkCommonLayoutProps | 'className' | 'children' | LayoutEventProps | FlexGridPropKeys | DisallowedShorthandProps>;
+/**
+ * Component-specific props for BpkBox
+ * Includes all Box props except those in BpkCommonLayoutProps
+ */
+export interface BpkBoxSpecificProps extends Omit<RemoveCommonProps<BoxProps>, BpkBoxResponsiveLayoutPropKeys>, BpkBoxResponsiveLayoutProps, Omit<BpkFlexGridProps, BpkBoxResponsiveLayoutPropKeys> {
+}
+/**
+ * Props for BpkBox component
+ * Combines Box-specific props with Backpack common layout props
+ * and reintroduces a minimal set of interaction props.
+ */
+type BoxEventProps = Pick<BoxProps, 'onClick' | 'onFocus' | 'onBlur'>;
+export interface BpkBoxProps extends BpkCommonLayoutProps, BpkBoxSpecificProps {
+    children?: ReactNode;
+    onClick?: BoxEventProps['onClick'];
+    onFocus?: BoxEventProps['onFocus'];
+    onBlur?: BoxEventProps['onBlur'];
+}
+/**
+ * Component-specific props for BpkFlex
+ * Includes all Flex props except those in BpkCommonLayoutProps
+ */
+export interface BpkFlexSpecificProps extends RemoveCommonProps<FlexProps> {
+    direction?: BpkResponsiveValue<FlexProps['flexDirection']>;
+    justify?: BpkResponsiveValue<FlexProps['justifyContent']>;
+    align?: BpkResponsiveValue<FlexProps['alignItems']>;
+    wrap?: BpkResponsiveValue<FlexProps['flexWrap']>;
+    grow?: BpkResponsiveValue<FlexProps['flexGrow']>;
+    shrink?: BpkResponsiveValue<FlexProps['flexShrink']>;
+    basis?: BpkResponsiveValue<BpkBasisValue>;
+    inline?: boolean;
+}
+/**
+ * Props for BpkFlex component
+ * Combines Flex-specific props with Backpack common layout props
+ */
+export interface BpkFlexProps extends BpkCommonLayoutProps, BpkFlexSpecificProps {
+    children?: ReactNode;
+}
+/**
+ * Component-specific props for BpkGrid
+ * Includes all Grid props except those in BpkCommonLayoutProps
+ */
+export interface BpkGridSpecificProps extends RemoveCommonProps<GridProps> {
+    justify?: BpkResponsiveValue<GridProps['justifyContent']>;
+    align?: BpkResponsiveValue<GridProps['alignItems']>;
+    templateColumns?: BpkResponsiveValue<GridProps['gridTemplateColumns']>;
+    templateRows?: BpkResponsiveValue<GridProps['gridTemplateRows']>;
+    templateAreas?: BpkResponsiveValue<GridProps['gridTemplateAreas']>;
+    autoFlow?: BpkResponsiveValue<GridProps['gridAutoFlow']>;
+    autoRows?: BpkResponsiveValue<GridProps['gridAutoRows']>;
+    autoColumns?: BpkResponsiveValue<GridProps['gridAutoColumns']>;
+    rowGap?: BpkResponsiveValue<BpkSpacingValue>;
+    columnGap?: BpkResponsiveValue<BpkSpacingValue>;
+    column?: BpkResponsiveValue<GridProps['gridColumn']>;
+    row?: BpkResponsiveValue<GridProps['gridRow']>;
+    inline?: boolean;
+}
+/**
+ * Props for BpkGrid component
+ * Combines Grid-specific props with Backpack common layout props
+ */
+export interface BpkGridProps extends BpkCommonLayoutProps, BpkGridSpecificProps {
+    children?: ReactNode;
+}
+/**
+ * Component-specific props for BpkGridItem
+ * Includes all GridItem props except those in BpkCommonLayoutProps
+ */
+export interface BpkGridItemSpecificProps extends RemoveCommonProps<GridItemProps> {
+    area?: GridItemProps['area'];
+    colEnd?: GridItemProps['colEnd'];
+    colStart?: GridItemProps['colStart'];
+    colSpan?: GridItemProps['colSpan'];
+    rowEnd?: GridItemProps['rowEnd'];
+    rowStart?: GridItemProps['rowStart'];
+    rowSpan?: GridItemProps['rowSpan'];
+}
+/**
+ * Props for BpkGridItem component
+ * Combines GridItem-specific props with Backpack common layout props
+ */
+export interface BpkGridItemProps extends BpkCommonLayoutProps, BpkGridItemSpecificProps {
+    children?: ReactNode;
+}
+type StackOptionKeysType = typeof StackOptionKeys[number];
+/**
+ * Overrides StackOptions to support BpkResponsiveValue
+ */
+type BpkStackOptions = {
+    [K in StackOptionKeysType]?: K extends keyof StackProps ? BpkResponsiveValue<StackProps[K]> | StackProps[K] : never;
+};
+/**
+ * Component-specific props for BpkStack
+ * Includes all Stack props except those in BpkCommonLayoutProps
+ * Overrides StackOptions to support BpkResponsiveValue
+ */
+export interface BpkStackSpecificProps extends Omit<RemoveCommonProps<StackProps>, StackOptionKeysType>, BpkStackOptions, BpkFlexGridProps {
+}
+/**
+ * Props for BpkStack component
+ * Combines Stack-specific props with Backpack common layout props
+ */
+export interface BpkStackProps extends BpkCommonLayoutProps, BpkStackSpecificProps {
+    children?: ReactNode;
+}
+export type { BpkCommonLayoutProps };

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyscanner/backpack-web",
-  "version": "41.6.0",
+  "version": "41.7.0-beta-v1",
   "description": "Backpack Design System web library",
   "repository": {
     "type": "git",
@@ -22,6 +22,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@chakra-ui/react": "^3.30.0",
     "@floating-ui/react": "^0.26.12",
     "@popperjs/core": "^2.11.8",
     "@radix-ui/react-compose-refs": "^1.1.1",