Updating the docs for framework/commerce

README.md

@@ -29,7 +29,7 @@ Next.js Commerce integrates out-of-the-box with BigCommerce and Shopify. We plan
 ## Considerations
 
 - `framework/commerce` contains all types, helpers and functions to be used as base to build a new **provider**.
-- **Providers** live under `framework`'s root folder and they will extend Next.js Commerce types and functionality.
+- **Providers** live under `framework`'s root folder and they will extend Next.js Commerce types and functionality (`framework/commerce`).
 - **Features API** is to ensure feature parity between the UI and the Provider. The UI should update accordingly and no extra code should be bundled. All extra configuration for features will live under `features` in `commerce.config.json` and if needed it can also be accessed programatically.
 - Each **provider** should add its corresponding `next.config.js` and `commerce.config.json` adding specific data related to the provider. For example in case of BigCommerce, the images CDN and additional API routes.
 - **Providers don't depend on anything that's specific to the application they're used in**. They only depend on `framework/commerce`, on their own framework folder and on some dependencies included in `package.json`
@@ -99,12 +99,6 @@ We'd recommend to duplicate a provider folder and push your providers SDK.
 
 If you succeeded building a provider, submit a PR so we can all enjoy it.
 
-## Work in progress
-
-We're using Github Projects to keep track of issues in progress and todo's. Here is our [Board](https://github.com/vercel/commerce/projects/1)
-
-People actively working on this project: @okbel & @lfades.
-
 ## Contribute
 
 Our commitment to Open Source can be found [here](https://vercel.com/oss).
@@ -113,11 +107,15 @@ Our commitment to Open Source can be found [here](https://vercel.com/oss).
 2. Create a new branch `git checkout -b MY_BRANCH_NAME`
 3. Install yarn: `npm install -g yarn`
 4. Install the dependencies: `yarn`
-5. Duplicate `.env.template` and rename it to `.env.local`.
+5. Duplicate `.env.template` and rename it to `.env.local`
-6. Add proper store values to `.env.local`.
+6. Add proper store values to `.env.local`
 7. Run `yarn dev` to build and watch for code changes
-8. The development branch is `canary` (this is the branch pull requests should be made against).
+
-   On a release, `canary` branch is rebased into `master`.
+## Work in progress
+
+We're using Github Projects to keep track of issues in progress and todo's. Here is our [Board](https://github.com/vercel/commerce/projects/1)
+
+People actively working on this project: @okbel & @lfades.
 
 ## Troubleshoot
 

framework/commerce/README.md

@@ -0,0 +1,350 @@
+# Table of Contents
+
+- [BigCommerce Storefront Data Hooks](#bigcommerce-storefront-data-hooks)
+  - [Installation](#installation)
+  - [General Usage](#general-usage)
+    - [CommerceProvider](#commerceprovider)
+    - [useLogin hook](#uselogin-hook)
+    - [useLogout](#uselogout)
+    - [useCustomer](#usecustomer)
+    - [useSignup](#usesignup)
+    - [usePrice](#useprice)
+  - [Cart Hooks](#cart-hooks)
+    - [useCart](#usecart)
+    - [useAddItem](#useadditem)
+    - [useUpdateItem](#useupdateitem)
+    - [useRemoveItem](#useremoveitem)
+  - [Wishlist Hooks](#wishlist-hooks)
+  - [Product Hooks and API](#product-hooks-and-api)
+    - [useSearch](#usesearch)
+    - [getAllProducts](#getallproducts)
+    - [getProduct](#getproduct)
+  - [More](#more)
+
+# Commerce Framework
+
+> The core commerce framework is under active development, new features and updates will be continuously added over time. Breaking changes are expected while we finish the API.
+
+The commerce framework ships multiple hooks and a Node.js API, both using an underlying headless e-commerce platform, which we call commerce providers.
+
+The core features are:
+
+- Code splitted hooks for data fetching using [SWR](https://swr.vercel.app/), and to handle common user actions
+- A Node.js API for initial data population, static generation of content and for creating the API endpoints that connect to the hooks, if required.
+
+## Commerce Hooks
+
+A commerce hook is a [React hook](https://reactjs.org/docs/hooks-intro.html) that's connected to a commerce provider. They focus on user actions and data fetching of data that wasn't statically generated.
+
+Data fetching hooks use [SWR](https://swr.vercel.app/) underneath and you're welcome to use any of its [return values](https://swr.vercel.app/docs/options#return-values) and [options](https://swr.vercel.app/docs/options#options). For example, using the `useCustomer` hook:
+
+```jsx
+const { data, isLoading, error } = useCustomer({
+  swrOptions: {
+    revalidateOnFocus: true,
+  },
+})
+```
+
+### CommerceProvider
+
+This component adds the provider config and handlers to the context of your React tree for it's children. You can optionally pass the `locale` to it:
+
+```jsx
+import { CommerceProvider } from '@framework'
+
+const App = ({ locale = 'en-US', children }) => {
+  return <CommerceProvider locale={locale}>{children}</CommerceProvider>
+}
+```
+
+## Authentication Hooks
+
+### useSignup
+
+Returns a _signup_ function that can be used to sign up the current visitor:
+
+```jsx
+import useSignup from '@framework/auth/use-signup'
+
+const SignupView = () => {
+  const signup = useSignup()
+
+  const handleSignup = async () => {
+    await signup({
+      email,
+      firstName,
+      lastName,
+      password,
+    })
+  }
+
+  return <form onSubmit={handleSignup}>{children}</form>
+}
+```
+
+### useLogin
+
+Returns a _login_ function that can be used to sign in the current visitor into an existing customer:
+
+```jsx
+import useLogin from '@framework/auth/use-login'
+
+const LoginView = () => {
+  const login = useLogin()
+  const handleLogin = async () => {
+    await login({
+      email,
+      password,
+    })
+  }
+
+  return <form onSubmit={handleLogin}>{children}</form>
+}
+```
+
+### useLogout
+
+Returns a _logout_ function that signs out the current customer when called.
+
+```jsx
+import useLogout from '@framework/auth/use-logout'
+
+const LogoutLink = () => {
+  const logout = useLogout()
+  return <a onClick={() => logout()}>Logout</a>
+}
+```
+
+## Customer Hooks
+
+### useCustomer
+
+Fetches the data of the signed in customer:
+
+```jsx
+import useCustomer from '@framework/customer/use-customer'
+
+const Profile = () => {
+  const { data, isLoading, error } = useCustomer()
+
+  if (isLoading) return <p>Loading...</p>
+  if (error) return <p>{error.message}</p>
+  if (!data) return null
+
+  return <div>Hello, {data.firstName}</div>
+}
+```
+
+### usePrice
+
+Helper hook to format price according to commerce locale, and return discount if available.
+
+```jsx
+import usePrice from '@bigcommerce/storefront-data-hooks/use-price'
+...
+  const { price, discount, basePrice } = usePrice(
+    data && {
+      amount: data.cart_amount,
+      currencyCode: data.currency.code,
+    }
+  )
+...
+```
+
+## Cart Hooks
+
+### useCart
+
+Returns the current cart data for use
+
+```jsx
+...
+import useCart from '@bigcommerce/storefront-data-hooks/cart/use-cart'
+
+const countItem = (count: number, item: LineItem) => count + item.quantity
+
+const CartNumber = () => {
+  const { data } = useCart()
+  const itemsCount = data?.lineItems.reduce(countItem, 0) ?? 0
+
+  return itemsCount > 0 ? <span>{itemsCount}</span> : null
+}
+```
+
+### useAddItem
+
+```jsx
+...
+import useAddItem from '@bigcommerce/storefront-data-hooks/cart/use-add-item'
+
+const AddToCartButton = ({ productId, variantId }) => {
+  const addItem = useAddItem()
+
+  const addToCart = async () => {
+    await addItem({
+      productId,
+      variantId,
+    })
+  }
+
+  return <button onClick={addToCart}>Add To Cart</button>
+}
+...
+```
+
+### useUpdateItem
+
+```jsx
+...
+import useUpdateItem from '@bigcommerce/storefront-data-hooks/cart/use-update-item'
+
+const CartItem = ({ item }) => {
+  const [quantity, setQuantity] = useState(item.quantity)
+  const updateItem = useUpdateItem(item)
+
+  const updateQuantity = async (e) => {
+    const val = e.target.value
+    await updateItem({ quantity: val })
+  }
+
+  return (
+    <input
+      type="number"
+      max={99}
+      min={0}
+      value={quantity}
+      onChange={updateQuantity}
+    />
+  )
+}
+...
+```
+
+### useRemoveItem
+
+Provided with a cartItemId, will remove an item from the cart:
+
+```jsx
+...
+import useRemoveItem from '@bigcommerce/storefront-data-hooks/cart/use-remove-item'
+
+const RemoveButton = ({ item }) => {
+  const removeItem = useRemoveItem()
+
+  const handleRemove = async () => {
+    await removeItem({ id: item.id })
+  }
+
+  return <button onClick={handleRemove}>Remove</button>
+}
+...
+```
+
+## Wishlist Hooks
+
+Wishlist hooks are similar to cart hooks. See the below example for how to use `useWishlist`, `useAddItem`, and `useRemoveItem`.
+
+```jsx
+import useAddItem from '@bigcommerce/storefront-data-hooks/wishlist/use-add-item'
+import useRemoveItem from '@bigcommerce/storefront-data-hooks/wishlist/use-remove-item'
+import useWishlist from '@bigcommerce/storefront-data-hooks/wishlist/use-wishlist'
+
+const WishlistButton = ({ productId, variant }) => {
+  const addItem = useAddItem()
+  const removeItem = useRemoveItem()
+  const { data } = useWishlist()
+  const { data: customer } = useCustomer()
+  const itemInWishlist = data?.items?.find(
+    (item) =>
+      item.product_id === productId &&
+      item.variant_id === variant?.node.entityId
+  )
+
+  const handleWishlistChange = async (e) => {
+    e.preventDefault()
+
+    if (!customer) {
+      return
+    }
+
+    if (itemInWishlist) {
+      await removeItem({ id: itemInWishlist.id! })
+    } else {
+      await addItem({
+        productId,
+        variantId: variant?.node.entityId!,
+      })
+    }
+  }
+
+  return (
+    <button onClick={handleWishlistChange}>
+      <Heart fill={itemInWishlist ? 'var(--pink)' : 'none'} />
+    </button>
+  )
+}
+```
+
+## Product Hooks and API
+
+### useSearch
+
+`useSearch` handles searching the bigcommerce storefront product catalog by catalog, brand, and query string.
+
+```jsx
+...
+import useSearch from '@bigcommerce/storefront-data-hooks/products/use-search'
+
+const SearchPage = ({ searchString, category, brand, sortStr }) => {
+  const { data } = useSearch({
+    search: searchString || '',
+    categoryId: category?.entityId,
+    brandId: brand?.entityId,
+    sort: sortStr || '',
+  })
+
+  return (
+    <Grid layout="normal">
+      {data.products.map(({ node }) => (
+        <ProductCard key={node.path} product={node} />
+      ))}
+    </Grid>
+  )
+}
+```
+
+### getAllProducts
+
+API function to retrieve a product list.
+
+```js
+import { getConfig } from '@bigcommerce/storefront-data-hooks/api'
+import getAllProducts from '@bigcommerce/storefront-data-hooks/api/operations/get-all-products'
+
+const { products } = await getAllProducts({
+  variables: { field: 'featuredProducts', first: 6 },
+  config,
+  preview,
+})
+```
+
+### getProduct
+
+API product to retrieve a single product when provided with the product
+slug string.
+
+```js
+import { getConfig } from '@bigcommerce/storefront-data-hooks/api'
+import getProduct from '@bigcommerce/storefront-data-hooks/api/operations/get-product'
+
+const { product } = await getProduct({
+  variables: { slug },
+  config,
+  preview,
+})
+```
+
+## More
+
+Feel free to read through the source for more usage, and check the commerce vercel demo and commerce repo for usage examples: ([demo.vercel.store](https://demo.vercel.store/)) ([repo](https://github.com/vercel/commerce))