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

    0.0.1 • Public • Published

    bigcommerce-react-theme-components

    This project is under active development, new features and updates will be continuously added over time

    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'

    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.

    Example

    To see examples of the components in use, try the example app. To start the example app, simply go into the example, run yarn, and yarn start to view examples of the core product components, cart, and account 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
    }
    

    ReviewForm

    Props:

    onSubmit: (value: object) => boolean
    children?: any
    formConfig?: ReviewFormField[]
    styles?: any
    fill?: ReviewType
    
    interface ReviewType {
      name: string
      rating: number
      email: string
      text: string
      title: string
    }
    
    interface ReviewFormField {
      name: string
      label: string
      type?: string
      required?: boolean
      component?: any
    }
    

    Default form config

    [
      {
        name: 'rating',
        label: 'Rating',
        required: true,
        component: RatingSelect,
      },
      {
        name: 'name',
        label: 'Name',
        required: true,
      },
      {
        name: 'email',
        label: 'Email Address',
        required: true,
        type: 'email',
      },
      {
        name: 'title',
        label: 'Subject',
        required: true,
      },
      {
        name: 'text',
        label: 'Comments',
        required: true,
        component: TextArea,
      },
    ]
    

    Accepted classes from styles object:

    .reviewForm
    .saveButton
    .fieldWrapper
    .required
    

    Classes are also generated are also generated from the form config. For example for the name field, the following styles are accepted:

    .name-wrapper
    .name-label
    .name
    

    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
    

    SearchForm Component

    Props

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

    Default form config (Currently not needed but plans to expand for filters are in the works.):

    const searchFormConfig {
      {
        name: 'search',
        label: 'Search',
        type: 'search',
      },
    }
    

    Requires

    SearchFormSubmit component as a child of the form. Example: <Widgets.SearchFormSubmit>Product Search</Widgets.SearchFormSubmit>

    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 component 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
    

    CreateWishlist

    The CreateWishlist component renders a form to create a wishlist, allows for passed in css modules, and propagates the onSubmit event with the data formatted according to BigCommerce APIs. Note that the event object propagated up will contain a data property containing the data entered in the form.

    Props:

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

    The following styles are automatically provided to the styles prop:

    styles.wishlistForm
    styles.fieldWrapper
    styles.nameLabel
    styles.name
    styles.publicLabel
    styles.public
    styles.saveButton
    

    Orders

    OrderList

    The OrderList component requires a list of orders. If a product map is provided for the order list, product information for the orders will be displayed as well. For an example of how to build the product map, please check example/src/components/orders.tsx. The default OrderComponent is OrderRow. The OrderList component will provide all of it's props down to the OrderComponent that is passed in.

    Props:

    orders: Order[]
    productMap: any
    OrderComponent?: any
    styles?: any
    onOrderAction?: (action: string, order: Order) => void
    

    Styles:

    .orders
    

    OrderDetail

    The OrderDetail component displays the details of an order, and a list of the products pertaining to the order.

    Props:

    order: Order
    products: OrderProduct[]
    onOrderAction?: (action: string, order: Order, product?: OrderProduct) => void
    productComponent?: React.FunctionComponent
    styles: any
    

    Helpful Hooks

    useProductData

    This hook helps with fetching product data, provided that data fetching functions and a productId is passed in. See example app for usage examples.

    Args: productDataFunctions: ProductDataFetchType productId: string

    useProductImages

    This hooks helps with fetching product images when given an image fetching function, and a list of products. See example app for usage examples.

    Args: getProductImages: Function products: Product[]

    License

    MIT © BigCommerce

    Keywords

    none

    Install

    npm i bigcommerce-react-theme-components

    DownloadsWeekly Downloads

    1

    Version

    0.0.1

    License

    MIT

    Unpacked Size

    8.14 MB

    Total Files

    251

    Last publish

    Collaborators

    • jingtribe