@skyscanner/backpack-web 29.4.0 → 29.4.2

package/bpk-component-graphic-promotion/src/BpkGraphicPromo.d.ts

@@ -16,39 +16,31 @@
  * limitations under the License.
  */
 
+/// <reference types="react" />
 export declare const TEXT_ALIGN: {
-  readonly start: 'start';
-  readonly center: 'center';
-  readonly end: 'end';
+    readonly start: "start";
+    readonly center: "center";
+    readonly end: "end";
 };
 export type Props = {
-  className?: string | null;
-  contentId?: string | null;
-  tagline?: string | null;
-  headline: string;
-  subheading?: string | null;
-  sponsor?: {
-    label: string;
-    logo: string;
-    altText: string;
-  } | null;
-  buttonText: string;
-  onClick: () => void;
-  invertVertically?: boolean;
-  textAlign: typeof TEXT_ALIGN[keyof typeof TEXT_ALIGN];
-  style?: {};
+    className?: string | null;
+    contentId?: string | null;
+    tagline?: string | null;
+    headline: string;
+    subheading?: string | null;
+    /**
+     * An object that groups together all the sponsor related properties. This should only be provided if the graphic promo is sponsored, in which case all of the object's properties are required.
+     */
+    sponsor?: {
+        label: string;
+        logo: string;
+        altText: string;
+    } | null;
+    buttonText: string;
+    onClick: () => void;
+    invertVertically?: boolean;
+    textAlign: (typeof TEXT_ALIGN)[keyof typeof TEXT_ALIGN];
+    style?: {};
 };
-declare const BpkGraphicPromo: ({
-  buttonText,
-  className,
-  contentId,
-  headline,
-  invertVertically,
-  onClick,
-  sponsor,
-  style,
-  subheading,
-  tagline,
-  textAlign,
-}: Props) => JSX.Element;
+declare const BpkGraphicPromo: ({ buttonText, className, contentId, headline, invertVertically, onClick, sponsor, style, subheading, tagline, textAlign, }: Props) => JSX.Element;
 export default BpkGraphicPromo;

package/bpk-component-horizontal-nav/src/BpkHorizontalNav.js

@@ -33,23 +33,6 @@ const getPos = ref => {
   return pos;
 };
 class BpkHorizontalNav extends Component {
-  static propTypes = {
-    children: PropTypes.node.isRequired,
-    autoScrollToSelected: PropTypes.bool,
-    className: PropTypes.string,
-    leadingScrollIndicatorClassName: PropTypes.string,
-    showUnderline: PropTypes.bool,
-    trailingScrollIndicatorClassName: PropTypes.string,
-    type: PropTypes.oneOf(Object.keys(HORIZONTAL_NAV_TYPES))
-  };
-  static defaultProps = {
-    autoScrollToSelected: false,
-    className: null,
-    leadingScrollIndicatorClassName: null,
-    showUnderline: true,
-    trailingScrollIndicatorClassName: null,
-    type: HORIZONTAL_NAV_TYPES.default
-  };
   constructor(props) {
     super(props);
     this.scrollRef = null;
@@ -147,5 +130,29 @@ class BpkHorizontalNav extends Component {
     );
   }
 }
+BpkHorizontalNav.propTypes = {
+  children: PropTypes.node.isRequired,
+  /**
+   * Ensures that the selected item is within view when loaded on narrow-screened devices.
+   */
+  autoScrollToSelected: PropTypes.bool,
+  className: PropTypes.string,
+  leadingScrollIndicatorClassName: PropTypes.string,
+  /**
+   * When set to "false", the bottom border on the component isn't included. This refers 
+   * to the underline on the whole "BpkHorizontalNav", not the line that appears under the selected item.
+   */
+  showUnderline: PropTypes.bool,
+  trailingScrollIndicatorClassName: PropTypes.string,
+  type: PropTypes.oneOf(Object.keys(HORIZONTAL_NAV_TYPES))
+};
+BpkHorizontalNav.defaultProps = {
+  autoScrollToSelected: false,
+  className: null,
+  leadingScrollIndicatorClassName: null,
+  showUnderline: true,
+  trailingScrollIndicatorClassName: null,
+  type: HORIZONTAL_NAV_TYPES.default
+};
 export default BpkHorizontalNav;
 export { HORIZONTAL_NAV_TYPES };

package/bpk-component-horizontal-nav/src/BpkHorizontalNavItem.js

@@ -25,23 +25,6 @@ const getClassName = cssModules(STYLES);
 // React Component class.
 // eslint-disable-next-line react/prefer-stateless-function
 class BpkHorizontalNavItem extends Component {
-  static propTypes = {
-    children: PropTypes.node.isRequired,
-    className: PropTypes.string,
-    disabled: PropTypes.bool,
-    href: PropTypes.string,
-    selected: PropTypes.bool,
-    spaceAround: PropTypes.bool,
-    type: PropTypes.oneOf(Object.keys(HORIZONTAL_NAV_TYPES))
-  };
-  static defaultProps = {
-    className: null,
-    disabled: false,
-    href: null,
-    selected: false,
-    spaceAround: false,
-    type: HORIZONTAL_NAV_TYPES.default
-  };
   render() {
     const {
       children,
@@ -84,6 +67,31 @@ class BpkHorizontalNavItem extends Component {
     });
   }
 }
+BpkHorizontalNavItem.propTypes = {
+  children: PropTypes.node.isRequired,
+  className: PropTypes.string,
+  /**
+   * **Note:**
+   * "disabled" and "selected" are mutually exclusive for true values, i.e. only one of them can be true for a given nav item.
+   */
+  disabled: PropTypes.bool,
+  href: PropTypes.string,
+  /**
+   * **Note:**
+   * "disabled" and "selected" are mutually exclusive for true values, i.e. only one of them can be true for a given nav item.
+   */
+  selected: PropTypes.bool,
+  spaceAround: PropTypes.bool,
+  type: PropTypes.oneOf(Object.keys(HORIZONTAL_NAV_TYPES))
+};
+BpkHorizontalNavItem.defaultProps = {
+  className: null,
+  disabled: false,
+  href: null,
+  selected: false,
+  spaceAround: false,
+  type: HORIZONTAL_NAV_TYPES.default
+};
 const themeAttributes = ['horizontalNavLinkColor', 'horizontalNavLinkHoverColor', 'horizontalNavLinkActiveColor', 'horizontalNavLinkSelectedColor', 'horizontalNavBarSelectedColor'];
 export { themeAttributes };
 export default BpkHorizontalNavItem;

package/bpk-component-image/src/BpkImage.d.ts

@@ -21,10 +21,13 @@ import BORDER_RADIUS_STYLES from './BpkImageBorderRadiusStyles';
 type BpkImageProps = {
     altText: string;
     src: string;
+    /**
+     * Note: The `aspectRatio` prop should be calculated as `width/height` of the original src image. It is used by the component to preserve space on screen while the image loads.
+     */
     aspectRatio: number;
     inView?: boolean;
     loading?: boolean;
-    borderRadiusStyle?: typeof BORDER_RADIUS_STYLES[keyof typeof BORDER_RADIUS_STYLES];
+    borderRadiusStyle?: (typeof BORDER_RADIUS_STYLES)[keyof typeof BORDER_RADIUS_STYLES];
     className?: string;
     onLoad?: (() => void) | null;
     style?: {};

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

@@ -30,11 +30,22 @@ export declare const INPUT_TYPES: {
     readonly password: "password";
     readonly tel: "tel";
 };
-type BaseProps = ComponentProps<'input'> & {
+type InputProps = {
+    /**
+     * **Required:** The id attribute of the input.
+     */
     id: string;
+    /**
+     * **Required:** The name attribute of the input.
+     */
     name: string;
+    /**
+     * **Required:** The value attribute of the input.
+     */
     value: string;
-    type?: typeof INPUT_TYPES[keyof typeof INPUT_TYPES];
+    type?: (typeof INPUT_TYPES)[keyof typeof INPUT_TYPES];
+};
+type BaseProps = InputProps & ComponentProps<'input'> & {
     valid?: boolean | null;
     large?: boolean;
     docked?: boolean;
@@ -49,7 +60,10 @@ export type PropsWithoutClearButonMode = BaseProps & {
     onClear?: ((e?: SyntheticEvent<HTMLButtonElement>) => void) | null;
 };
 export type PropsWithClearButtonMode = BaseProps & {
-    clearButtonMode: typeof CLEAR_BUTTON_MODES[keyof Omit<typeof CLEAR_BUTTON_MODES, 'never'>];
+    /**
+     * When `clearButtonMode` is set to `always`, validity icons will not appear.
+     */
+    clearButtonMode: (typeof CLEAR_BUTTON_MODES)[keyof Omit<typeof CLEAR_BUTTON_MODES, 'never'>];
     clearButtonLabel: string;
     onClear: (e?: SyntheticEvent<HTMLButtonElement>) => void;
 };

package/bpk-component-input/src/common-types.js

@@ -29,6 +29,9 @@ export const INPUT_TYPES = {
   password: 'password',
   tel: 'tel'
 };
+
+// Declaring this type here as react docgen gets confused and reads them as native input types
+
 // TODO - this function should be removed once all input examples have been migrated to TS
 export const clearablePropType = (props, propName, componentName) => {
   const createError = message => new Error(`Invalid prop \`${propName}\` supplied to \`${componentName}\`. ${message}.`);
@@ -48,6 +51,8 @@ export const clearablePropType = (props, propName, componentName) => {
   }
   return null;
 };
+
+// TODO - this should be removed once all input examples have been migrated to TS
 export const propTypes = {
   id: PropTypes.string.isRequired,
   name: PropTypes.string.isRequired,
@@ -65,6 +70,8 @@ export const propTypes = {
   clearButtonLabel: clearablePropType,
   onClear: clearablePropType
 };
+
+// TODO - this should be removed once all input examples have been migrated to TS
 export const defaultProps = {
   type: INPUT_TYPES.text,
   valid: null,

package/bpk-component-input/src/withOpenEvents.d.ts

@@ -17,8 +17,20 @@
  */
 
 import type { ComponentType, ReactElement, UIEvent, ComponentProps } from 'react';
-type WithOpenEventsProps = {
+export type WithOpenEventsProps = {
+    /**
+     * It is important you pass the `isOpen` prop, as it is necessary to work around an IE bug.
+     */
     isOpen?: boolean;
+    /**
+     * The onOpen callback is called on the following events:
+     * click
+     * focus
+     * touchend
+     * keydown (Enter key)
+     * keyup (Space key)
+     * You can still attach custom handlers for these events as they will still be called. All other key events are prevented.
+     */
     onOpen?: () => void;
     hasTouchSupport?: boolean;
 };

package/bpk-component-list/src/BpkList.js

@@ -41,7 +41,10 @@ const BpkList = props => {
 BpkList.propTypes = {
   children: PropTypes.oneOfType([PropTypes.arrayOf(PropTypes.node), PropTypes.node]).isRequired,
   ordered: PropTypes.bool,
-  className: PropTypes.string
+  className: PropTypes.string,
+  ariaLabel: PropTypes.string,
+  ariaLabelledby: PropTypes.string,
+  title: PropTypes.string
 };
 BpkList.defaultProps = {
   ordered: false,

package/bpk-component-map/index.js

@@ -17,7 +17,7 @@
  */import BpkMap from "./src/BpkMap";
 import BpkIconMarker from "./src/BpkIconMarker";
 import BpkPriceMarker, { PRICE_MARKER_STATUSES } from "./src/BpkPriceMarker";
-import BpkPriceMarkerV2, { MARKER_STATUSES } from "./src/BpkPriceMarkerV2/BpkPriceMarker";
+import { BpkPriceMarkerV2, MARKER_STATUSES } from "./src/BpkPriceMarkerV2/BpkPriceMarker";
 import BpkOverlayView from "./src/BpkOverlayView";
 import withGoogleMapsScript from "./src/withGoogleMapsScript";
 import { defaultIconMarkerThemeAttributes, priceMarkerThemeAttributes } from "./src/themeAttributes";

package/bpk-component-map/src/BpkMap.js

@@ -106,12 +106,18 @@ const BpkMap = props => {
   });
 };
 BpkMap.propTypes = {
+  /**
+   * Note: One of `bounds` and `center` must be provided.
+   */
   bounds: PropTypes.shape({
     south: PropTypes.number.isRequired,
     west: PropTypes.number.isRequired,
     north: PropTypes.number.isRequired,
     east: PropTypes.number.isRequired
   }),
+  /**
+   * Note: One of `bounds` and `center` must be provided.
+   */
   center: LatLongPropType,
   children: PropTypes.node,
   greedyGestureHandling: PropTypes.bool,

package/bpk-component-map/src/BpkPriceMarkerV2/BpkPriceMarker.d.ts

@@ -15,39 +15,28 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { Node } from 'react';
-import { MouseEvent, ReactNode } from 'react';
-
-export const MARKER_STATUSES = {
-  unselected: 'unselected',
-  selected: 'selected',
-  previous_selected: 'previous_selected',
-} as const;
 
+import type { MouseEvent, ReactNode } from 'react';
+export declare const MARKER_STATUSES: {
+    readonly unselected: "unselected";
+    readonly selected: "selected";
+    readonly previous_selected: "previous_selected";
+};
 export type Status = (typeof MARKER_STATUSES)[keyof typeof MARKER_STATUSES];
-
 type Props = {
-  label: string;
-  icon?: ReactNode;
-  accessibilityLabel: string;
-  position: {
-    latitude: number;
-    longitude: number;
-  };
-  className?: string;
-  onClick?: (event: MouseEvent) => void;
-  buttonProps?: { [key: string]: string };
-  status?: Status;
+    label: string;
+    icon?: ReactNode;
+    accessibilityLabel: string;
+    position: {
+        latitude: number;
+        longitude: number;
+    };
+    className?: string;
+    onClick?: (event: MouseEvent) => void;
+    buttonProps?: {
+        [key: string]: string;
+    };
+    status?: Status;
 };
-
-declare const BpkPriceMarkerV2: ({
-  label,
-  position,
-  className,
-  onClick,
-  buttonProps,
-  status,
-  style,
-}: Props) => JSX.Element;
-
-export default BpkPriceMarkerV2;
+export declare const BpkPriceMarkerV2: (props: Props) => JSX.Element;
+export {};

package/bpk-component-map/src/BpkPriceMarkerV2/BpkPriceMarker.js

@@ -28,7 +28,7 @@ export const MARKER_STATUSES = {
   selected: 'selected',
   previous_selected: 'previous_selected'
 };
-const BpkPriceMarkerV2 = props => {
+export const BpkPriceMarkerV2 = props => {
   const {
     accessibilityLabel,
     buttonProps,
@@ -60,5 +60,4 @@ const BpkPriceMarkerV2 = props => {
       })
     })
   });
-};
-export default BpkPriceMarkerV2;
+};

package/bpk-component-mobile-scroll-container/src/BpkMobileScrollContainer.js

@@ -58,27 +58,26 @@ const computeScrollIndicatorClassName = (scrollerEl, leadingIndicatorClassName =
   }
   return classNames;
 };
+const propTypes = {
+  children: PropTypes.node.isRequired,
+  scrollerRef: PropTypes.func,
+  innerContainerTagName: PropTypes.string,
+  className: PropTypes.string,
+  leadingIndicatorClassName: PropTypes.string,
+  trailingIndicatorClassName: PropTypes.string,
+  style: PropTypes.object,
+  showScrollbar: PropTypes.bool
+};
+const defaultProps = {
+  scrollerRef: null,
+  innerContainerTagName: 'div',
+  className: null,
+  leadingIndicatorClassName: null,
+  trailingIndicatorClassName: null,
+  style: null,
+  showScrollbar: false
+};
 class BpkMobileScrollContainer extends Component {
-  static propTypes = {
-    children: PropTypes.node.isRequired,
-    scrollerRef: PropTypes.func,
-    innerContainerTagName: PropTypes.string,
-    className: PropTypes.string,
-    leadingIndicatorClassName: PropTypes.string,
-    trailingIndicatorClassName: PropTypes.string,
-    style: PropTypes.object,
-    // eslint-disable-line react/forbid-prop-types
-    showScrollbar: PropTypes.bool
-  };
-  static defaultProps = {
-    scrollerRef: null,
-    innerContainerTagName: 'div',
-    className: null,
-    leadingIndicatorClassName: null,
-    trailingIndicatorClassName: null,
-    style: null,
-    showScrollbar: false
-  };
   constructor() {
     super();
     this.state = {
@@ -167,5 +166,11 @@ class BpkMobileScrollContainer extends Component {
     });
   }
 }
+BpkMobileScrollContainer.propTypes = {
+  ...propTypes
+};
+BpkMobileScrollContainer.defaultProps = {
+  ...defaultProps
+};
 export default BpkMobileScrollContainer;
 export { computeScrollBarAwareHeight, computeScrollIndicatorClassName };

package/bpk-component-modal/src/BpkModal.d.ts

@@ -29,7 +29,13 @@ export type Props = Partial<ModalDialogProps> & {
     onClose?: (arg0?: TouchEvent | MouseEvent | KeyboardEvent, arg1?: {
         source: 'ESCAPE' | 'DOCUMENT_CLICK';
     }) => void;
+    /**
+     * Because this component uses a modal on mobile viewports, you need to let it know what
+     * the root element of your application is by returning its DOM node via this prop
+     * This is to "hide" your application from screen readers whilst the modal is open.
+     * The "pagewrap" element id is a convention we use internally at Skyscanner. In most cases it should "just work".
+     */
     getApplicationElement: () => HTMLElement | null;
 };
-declare const BpkModal: ({ title, onClose, className, contentClassName, closeLabel, closeText, wide, showHeader, fullScreenOnMobile, fullScreen, padded, accessoryView, renderTarget, isIphone, closeOnScrimClick, closeOnEscPressed, dialogRef, isOpen, ...rest }: Props) => JSX.Element;
+declare const BpkModal: ({ accessoryView, className, closeLabel, closeOnEscPressed, closeOnScrimClick, closeText, contentClassName, dialogRef, fullScreen, fullScreenOnMobile, isIphone, isOpen, onClose, padded, renderTarget, showHeader, title, wide, ...rest }: Props) => JSX.Element;
 export default BpkModal;

package/bpk-component-modal/src/BpkModalInner.d.ts

@@ -33,7 +33,10 @@ export type Props = {
     title?: string | null;
     closeLabel?: string;
     closeText?: string | null;
+    /**
+     * The accessory view allows for icons and actions to be placed in front of the main title inside the modal header. To be used with `BpkNavigationBarButtonLink`
+     */
     accessoryView?: ReactNode;
 };
-declare const BpkModalInner: ({ isIphone, id, dialogRef, children, title, onClose, className, contentClassName, closeLabel, closeText, wide, showHeader, fullScreenOnMobile, fullScreen, padded, accessoryView, }: Props) => JSX.Element;
+declare const BpkModalInner: ({ accessoryView, children, className, closeLabel, closeText, contentClassName, dialogRef, fullScreen, fullScreenOnMobile, id, isIphone, onClose, padded, showHeader, title, wide, }: Props) => JSX.Element;
 export default BpkModalInner;

package/bpk-component-navigation-bar/src/BpkNavigationBar.js

@@ -60,6 +60,7 @@ const BpkNavigationBar = props => {
   );
 };
 BpkNavigationBar.propTypes = {
+  id: PropTypes.string.isRequired,
   title: PropTypes.node.isRequired,
   className: PropTypes.string,
   leadingButton: PropTypes.element,

package/bpk-component-nudger/src/BpkConfigurableNudger.d.ts

@@ -20,9 +20,25 @@
 import { type CommonProps } from './common-types';
 type Props = CommonProps & {
     inputClassName?: string | null;
+    /**
+     * A simple function that will allow you to set the format of the display value e.g. local dates or times.
+     */
     formatValue: (arg0: any) => string;
+    /**
+     * Function that handle the incrementing of the current selected value.
+     */
     incrementValue: (arg0: any) => string | number;
+    /**
+     * Function that handle the decrementing of the current selected value.
+     */
     decrementValue: (arg0: any) => string | number;
+    /**
+     * Given `a` and `b`:
+     *   - If `a` is less than `b` then `compareValues(a, b)` should return a value less than `0`
+     *   - If  `a` and `b` are equal then `compareValues(a, b)` should return exactly `0`
+     *   - If `a` is greater than `b` then `compareValues(a, b)` should return a value greater than `0`
+     * We use this along with the `min` and `max` values to determine when we should disable the increment and decrement buttons. This is inspired by the `compareFunction` in [Array.prototype.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Description)
+     */
     compareValues: (arg0: any, arg1: any) => number;
 };
 declare const BpkConfigurableNudger: ({ buttonType, className, compareValues, decreaseButtonLabel, decrementValue, formatValue, id, increaseButtonLabel, incrementValue, inputClassName, max, min, onChange, value, ...rest }: Props) => JSX.Element;

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

@@ -17,7 +17,10 @@
  */
 
 import type { ReactNode } from "react";
-import type { BUTTON_TYPES } from "../../bpk-component-button/src/BpkButtonV2/common-types";
+export declare const BUTTON_TYPES: {
+    readonly secondary: "secondary";
+    readonly secondaryOnDark: "secondary-on-dark";
+};
 export type CommonProps = {
     id: string;
     min: string | number;
@@ -25,9 +28,22 @@ export type CommonProps = {
     value: string | number;
     onChange: (arg0: any) => void | null;
     className?: string | null;
+    /**
+     * This is the label that will be read out when screen reader users tab to the increase button. Make sure you use a descriptive label.
+     */
+    /**
+     * Function that handle the incrementing of the current selected value.
+     */
     increaseButtonLabel: string;
+    /**
+     * This is the label that will be read out when screen reader users tab to the decrease button. Make sure you use a descriptive label
+     */
     decreaseButtonLabel: string;
     buttonType?: keyof typeof BUTTON_TYPES;
+    /**
+     * Title, subtitle and icon together make up the label for the nudger.
+     * This label will be read aloud as a whole by screen readers. They all are optional props, however, if you wish to use a label then you will need to pass a title as the label will not work without it.
+     */
     title?: string;
     subtitle?: string;
     icon?: ReactNode;

package/bpk-component-nudger/src/common-types.js

@@ -1 +1,22 @@
-export {};
+/*
+ * 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.
+ */
+
+export const BUTTON_TYPES = {
+  secondary: 'secondary',
+  secondaryOnDark: 'secondary-on-dark'
+};

package/bpk-component-overlay/src/BpkOverlay.d.ts

@@ -36,11 +36,16 @@ export declare const OVERLAY_TYPES: {
     readonly vignette: "vignette";
     readonly off: "off";
 };
-export type OverlayType = typeof OVERLAY_TYPES[keyof typeof OVERLAY_TYPES];
-export type Props = ComponentProps<'div'> & {
+export type OverlayType = (typeof OVERLAY_TYPES)[keyof typeof OVERLAY_TYPES];
+type BpkOverlayProps = {
+    /**
+     * **Required:** The content to be rendered within the overlay.
+     */
     children: ReactNode;
-    overlayType?: OverlayType;
     className?: string;
+};
+export type Props = BpkOverlayProps & ComponentProps<'div'> & {
+    overlayType?: OverlayType;
     foregroundContent?: ReactNode;
 };
 declare const BpkOverlay: (props: Props) => JSX.Element;