@bigcommerce/bigcommerce-react-theme-components
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.1 • Public • Published

    bigcommerce-react-theme-components

    BigCommerce theme components built for Preact and React

    NPM JavaScript Style Guide

    BigCommerce React Theme Components are a set of core building blocks used to create a UI for your headless BigCommerce app or theme. Use some of the pre-made UI components found in the ui/ directory or build your own using the components in the core/ directory.

    See: BigCommerce Developer Docs.

    1. Create an API account from your store dashboard.
    2. Connect your app or theme to the BigCommerce API using your credentials.
    3. Send or retrieve data to/from your store and use it into your React app theme components.

    Install

    For now, until we deploy a package to NPM, you'll want to use the link feature for npm.

    1. Copy this repo into a directory of your choosing within your project.
    2. in your package.json, add an entry under dependencies for "storefront-ui-components": "link:../YOUR/PATH/TO/THE/REPO" 2.1 For example, since our example app is in the root dir, the link to the package in that package.json is "link:.."
    3. run
    yarn install
    1. Now you can import components from the library using import { Core, Widget } from 'storefront-ui-components'

    Usage

    import * as React from 'react'
     
    import { Core, Widget } from 'storefront-ui-components'
     
    class Example extends React.Component {
      render () {
        return (
            <Core.ProductTitle
              tag="h1"
              componentClass="bc-example-product-title"
              componentID="123-title"
              text='Example Product'
              dataAttributes={{['data-title']: 'bc-title-component', ['aria-label']: 'Example Product'}}
            />
        )
      }
    }

    Components

    ? Optional props for each Component ** Component accepts children element overrides

    Core Components

    ProductTitle

    Props:

    tag?: string default: h2
    text: string
    classes?: string
    tagID?: string
    styles?: object
    dataAttributes?: object
    

    ProductDescription

    Props:

    tag?: string default: div
    text: string
    classes?: string
    styles?: object
    

    ProductImage

    Props:

    src: string
    altText?: string
    wrapperClasses?: string
    classes?: string
    styles?: object
    

    ProductPrice

    Props:

    price: number
    salePrice: number
    currencySettings: object
    tag?: string default: span
    classes?: string
    tagID?: string
    styles?: object
    dataAttributes?: object
    hasSalePrice?: boolean default: false
    

    ProductBrand

    Props:

    text: string
    tag?: string default: span
    classes?: string
    styles?: object
    

    ProductCondition

    Props:

    text: string
    tag?: string default: span
    classes?: string
    styles?: object
    

    ProductCondition

    Props:

    text: string
    tag?: string default: span
    classes?: string
    styles?: object
    

    ProductInventory

    Props:

    tag?: string default: span
    classes?: string
    styles?: object
    showInventoryLevel?: boolean
    inventoryLevel: number
    showWarning?: boolean
    inventoryWarningLevel: number
    warningMessage?: string
    

    ProductSKU

    Props:

    text: string
    tag?: string default: span
    classes?: string
    styles?: object
    

    ProductSpecs

    Props:

    tag?: string default: ul
    textObject: object
    customFields?: array
    classes?: string
    styles?: object
    

    ProductReview

    Props:

    review: ReviewData
    tag?: string
    classes?: string
    tagID?: string
    styles?: object
    dataAttributes?: object
    
    interface ReviewData {
      date_created: string
      date_modified: string
      date_reviewed: string
      email: string
      id: number
      name: string
      rating: number
      status: string
      text: string
      title: string
    }
    

    Utility Components

    Notification

    Props:

    type?: string
    message: string
    classes?: string
    styles?: object
    

    The type options for the notification Components are success (default), info, error, and warning.

    Widget/UI Components

    ProductCard **

    This can be overridden by adding your own JSX children.

    Props:

    product: object
    image: object
    brand: object
    cardClasses?: string
    cardStyles?: object
    

    Default product card utilizes the following core components:

    • ProductImage
    • ProductTitle
    • ProductCondition
    • ProductPrice
    • Brand

    ProductReviews **

    This can be overridden by adding your own JSX children.

    Props:

    reviews: object
    tag?: string
    classes?: string
    tagID?: string
    styles?: object
    dataAttributes?: object
    

    Default product reviews utilizes the following core components:

    • ProductReview

    ProductDetailPage **

    This can be overridden by adding your own JSX children.

    Props:

    product: ProductObject
    image: ImageObject
    brand: BrandObject
    reviews?: object
    specs?: string[]
    currencySettings?: object
    PDPClasses?: string
    PDPStyles?: object
    
    interface ProductObject {
      name: string
      description: string
      condition: string
      price: number
      sale_price: number
      sku: string
      weight: number
      width: number
      height: number
      depth: number
      reviews_count: number
      reviews_rating_sum: number
    }
    
    interface ImageObject {
      url_standard: string
      meta: string
    }
    
    interface BrandObject {
      name: string
    }
    

    Default product reviews utilizes the following core/UI components:

    • ProductImage
    • ProductTitle
    • ProductCondition
    • ProductBrand
    • ProductPrice
    • StarRating
    • ProductSKU
    • ProductForm
    • Description
    • ProductSpecs
    • ProductReviews

    ProductQuickView **

    This can be overridden by adding your own JSX children.

    Props:

    product: ProductObject
    image: ImageObject
    brand: BrandObject
    currencySettings?: object
    PDPClasses?: string
    PDPStyles?: object
    
    interface ProductObject {
      name: string
      description: string
      condition: string
      price: number
      sale_price: number
      sku: string
      reviews_count: number
      reviews_rating_sum: number
    }
    
    interface ImageObject {
      url_standard: string
      meta: string
    }
    
    interface BrandObject {
      name: string
    }
    

    Default product reviews utilizes the following core components:

    • ProductImage
    • ProductTitle
    • ProductCondition
    • ProductBrand
    • ProductPrice
    • StarRating
    • ProductSKU
    • ProductForm
    • Description

    Cart Components

    Provider **

    This can be overridden by adding your own JSX children. This component is a provider pattern that will pass cart, style, and event props down to any children passed in.

    Props:

    cart: CartType
    children: any
    styles?: object
    onUpdate: (method: string, id: string, payload: object) => void
    onCheckout?: (value: object) => boolean
    

    Default Cart children are:

    • CartItems
    • Subtotal
    • Checkout

    All cart children are provided with props of

    • cart
    • styles
    • onUpdate
    • onCheckout

    Note that the above styles object is passed to all children, and can style the children components using the following classes:

    • cartProvider
    • cartItems
    • cartItem
    • cartItemPrices
    • cartItemTotal
    • cartSubtotal
    • cartSubtotalText
    • cartCheckout

    CartItems **

    Given a cart object with a lineItems object from a bigcommerce cart api call, this object will display the line items with a default Item component that can be overriden. Note that all props can already be provided by CartProvider above.

    Props:

    cart: CartType
    onUpdate: (method: string, id: string, payload: object) => void
    styles?: any
    ItemComponent?: any
    

    Note: ItemComponent default is the pre-written CartItem shown in examples, and is automatically provided with the same props as CartItems and an additional item prop of type CartItem type

    Checkout **

    Simply a button that will trigger the onCheckout event provided by the provider when clicked. Default button text will read Checkout, but can be overridden by passing in any children to the component.

    Props:

    children: object | string
    onCheckout: (method: string, id: string, payload: object) => void
    styles?: any
    

    Subtotal **

    Provided with a cart object from the provider, this component will display the total cart amount based on the cart currency.

    Props:

    cart: object
    styles?: any
    

    Product Form Components

    ProductForm

    Displays a product form for a passed in product, and provides certain props for children, and events for change and updates.

    Props:

    product: object
    action: string
    children: any
    onChange?: (value: object) => void
    onSubmit?: (value: object) => boolean
    method?: string
    classes?: string
    styles?: object
    

    All children are provided with the following props:

    • product
    • formData
    • onFormChange
    • onFormInit

    ProductModifiers

    Displays product options and modifiers based on modifier and option values from API calls. Also provides sensible defaults for dropdowns, checkboxes, text, and date modifiers.

    Props:

    modifiers: ModifierConfig[]
    map: object
    onFormChange?: (value: object) => void
    onFormInit?: (value: object) => void
    

    If further modifiers are desired, simply pass in a map prop to modifiers that holds any custom modifiers, using format below, which also show current default modifiers:

    const ModifierMap = {
      dropdown: Dropdown,
      checkbox: Checkbox,
      text: Text,
      date: DateInput,
    }
    

    Note that the key in the map must relate to the option/modifier type set in BigCommerce API.

    All modifier components are provided with modifier data, and an onFormChange event, which propagates all the way up to the above form compnent, if there is one.

    Login

    LoginForm component

    Displays a login form with custom onSubmit, action, and children if necessary.

    Props:

    onSubmit: (value: object) => boolean
    action: string
    children: any
    styles: any
    

    Default children are Username, Password, RememberMe, LoginButton, and ForgotPassword. All children are provided with styles passed into LoginForm component.

    The styles prop is passed to all children and will style the following classes for login:

    .loginForm
    .username
    .usernameLabel
    .password
    .passwordLabel
    .remember
    .rememberLabel
    .button
    .forgotLink
    

    Profile

    ProfileForm

    ProfileForm component displays certain profile fields from customer profile allowing for edit. Fields can be customized by passing in custom profileKeys prop to handle edit of properties, or by passing in new children, overriding default children generated from profileKeys

    Props:

    onSubmit: (value: object) => boolean
    children: any
    customer: CustomerProfile
    profileKeys: string[]
    styles: any
    

    Current profile keys handle:

    • First Name
    • Last Name
    • Phone
    • Email
    • Company

    The following styles are automatically picked up from the styles prop:

    .profileForm
    .fieldWrapper
    .first_name
    .first_name_label
    .last_name
    .last_name_label
    .company
    .company_label
    .phone
    .phone_label
    .email
    .email_label
    

    ShippingAddresses

    Given a list of addresses to display, the ShippingAddresses component iterates over the list, displays them using passed in AddressComponent prop, which defaults to the AddressCard component described below, and provides them with any passed in styles. styles object can contain styles for individual addresses (see below) and addresses for styling container.

    Props:

    addresses: AddressType[]
    AddressComponent: any
    styles: any
    

    AddressCard

    Displays the address and styles according.

    Props:

    address: AddressType
    styles: any
    

    The following styles are automatically picked up from the styles prop:

    .address
    .addressName
    .address1
    .address2
    .cityStateZip
    .country
    

    ShippingAddressForm

    The shipping address form will take a formConfig array to display the shipping address form.

    Props

    onSubmit: (value: object) => boolean
    children?: any
    formConfig?: AddressFormField[]
    styles?: any
    fill?: AddressType
    

    The default formConfig provided is as below:

    const defaultFormConfig = [
      {
        name: 'first_name',
        label: 'First Name',
        required: true,
      },
      {
        name: 'last_name',
        label: 'Last Name',
        required: true,
      },
      {
        name: 'company',
        label: 'Company',
      },
      {
        name: 'address1',
        label: 'Address Line 1',
        required: true,
      },
      {
        name: 'address2',
        label: 'Address Line 2',
      },
      {
        name: 'city',
        label: 'City',
        required: true,
      },
      {
        name: 'postal_code',
        label: 'Postal Code',
        required: true,
      },
      {
        name: 'state_or_province',
        label: 'State',
        required: true,
        component: StateSelect,
      },
      {
        name: 'country_code',
        label: 'State',
        required: true,
        component: CountrySelect,
      },
      {
        name: 'phone',
        label: 'Phone',
      },
    ]
    

    Note that custom components can be specified for any formConfig field. Custom components will be provided with styles, an onFieldChange event, the field config, and the current address object. The default component for fields is simply an input component.

    Field styles that are pulled from the styles object are provided for the wrapper, label, and the actual input component. For example, for the first_name field, the following classes will be accepted and passed down:

    .first_name
    .first_name-wrapper
    .first_name-label
    

    In addition to the above styles, the following styles are also provided:

    .addressForm
    .fieldWrapper
    .saveButton
    

    CountrySelect

    Displays select element with list of countries, uses the country-state-city npm package.

    Props

    onChange: (value: object) => void
    name: string
    value?: string
    className?: string
    id: string
    

    StateSelect

    Displays select element with list of selects when given a country code in the address object, uses the country-state-city npm package.

    Props

    onChange: (value: object) => void
    name: string
    value?: string
    className?: string
    id: string
    address?: AddressType
    

    Wishlists

    WishlistList

    Given a list of wishlists to display, the WishlistList component iterates over the list, displays them using passed in WishlistComponent prop, which defaults to the WishlistRow component described below, and provides them with any passed in styles. The onWishlistAction prop gets passed to each WishlistComponent, and will get passed with action and wishlist parameters

    Props:

    wishlists: Wishlist[]
    WishlistComponent?: any
    styles: any
    onWishlistAction: (action: string, wishlist: Wishlist) => void
    

    The following styles are automatically provided to the styles prop:

    .wishlists
    .wishlist
    .wishlistInfo
    .wishlistName
    .wishlistItems
    .wishlistShared
    .wishlistActions
    

    WishlistRow

    Given a wishlist object, this default component will display the wishlist name, pass in styles down to the component, and pass through any actions to the onWishlistAction prop. The current expectation is that code outside of the component will handle the actions below:

    click - triggered when wishlist name is clicked
    share - triggered when share button is clicked
    edit - triggered when edit button is clicked
    delete - triggered when delete button is clicked
    

    Note that onWishlistAction will be called with both an action and the wishlist object passed into WishlistRow

    Props:

    wishlist: Wishlist
    styles: any
    onWishlistAction: (action: string, wishlist: Wishlist) => void
    

    The following styles are automatically provided to the styles prop:

    .wishlist
    .wishlistInfo
    .wishlistName
    .wishlistItems
    .wishlistShared
    .wishlistActions
    .shareWishlistButton
    .editWishlistButton
    .deleteWishlistButton
    

    WishlistDetail

    The WishlistDetail component will display the wishlist passed in, along with the products in the wishlist. Due to api reponses, when passing in the wishlist, a list of products must be provided that match the wishlist items array. Each product in the wishlist will be displayed using the productComponent prop, which defaults to the WishlistProductRow component described below.

    Props:

    wishlist: Wishlist
    products: WishlistProduct[]
    onWishlistAction?: (action: string, wishlist: Wishlist) => void
    currencySettings: object
    productComponent?: React.Component
    styles: any
    

    The following styles are automatically provided to the styles prop:

    .wishlistDetail
    .wishlistDetailName
    

    WishlistProductRow

    The WishlistProductRow displays a product from a wishlist when given the product, passes in styles, and handles removal of products using the onWishlistAction pattern described above. When the product remove button is clicked, the provided onWishlistAction prop will be called with the remove_product action, and the new wishlist object without the product.

    Props:

    wishlist: Wishlist
    product: WishlistProduct
    currencySettings: object
    onWishlistAction: (action: string, wishlist: Wishlist) => void
    styles: any
    

    The following styles are automatically provided to the styles prop:

    styles.wishlistProduct
    styles.wishlistProductLink
    styles.wishlistPrice
    styles.wishlistProductRemove
    

    Storybook

    There currently aren't many storybooks, but they are being added as we work on the library. To run the storybook, simply run: yarn storybook and a browser window will open.

    License

    MIT © BigCommerce

    Keywords

    none

    Install

    npm i @bigcommerce/bigcommerce-react-theme-components

    DownloadsWeekly Downloads

    1

    Version

    0.0.1

    License

    MIT

    Unpacked Size

    1.96 MB

    Total Files

    64

    Last publish

    Collaborators

    • cilo
    • jorgemoya
    • bcnpmuser
    • icatalina
    • chris.boulton
    • bcandreik
    • davidchin
    • mattolson
    • pascal.zajac
    • amckemie
    • deini
    • chanceaclark
    • jairobc
    • jmwiese
    • pachanady
    • bc-jz