From 7a9740bad70893f5fb33e426c334e50d43b60a4e Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Mon, 3 Apr 2023 18:50:04 +0300
Subject: [PATCH] docs: added store how-to guide for categories (#3690)

---
 .../products/admin/manage-categories.mdx      |  10 +-
 docs/content/modules/products/categories.md   |   3 +-
 docs/content/modules/products/overview.mdx    |   3 +-
 .../modules/products/store/use-categories.mdx | 167 ++++++++++++++++++
 www/docs/sidebars.js                          |   5 +
 5 files changed, 183 insertions(+), 5 deletions(-)
 create mode 100644 docs/content/modules/products/store/use-categories.mdx

diff --git a/docs/content/modules/products/admin/manage-categories.mdx b/docs/content/modules/products/admin/manage-categories.mdx
index becd2b209e..a07321ab64 100644
--- a/docs/content/modules/products/admin/manage-categories.mdx
+++ b/docs/content/modules/products/admin/manage-categories.mdx
@@ -80,7 +80,7 @@ function Categories() {
     <div>
       {isLoading && <span>Loading...</span>}
       {product_categories && !product_categories.length && (
-        <span>No Product</span>
+        <span>No Categories</span>
       )}
       {product_categories && product_categories.length > 0 && (
         <ul>
@@ -675,4 +675,10 @@ The request returns the following fields:
 
 - `id`: The ID of the deleted category.
 - `object`: The type of object that was deleted. In this case, the value will be `product-category`.
-- `deleted`: A boolean value indicating whether the category was deleted.
\ No newline at end of file
+- `deleted`: A boolean value indicating whether the category was deleted.
+
+---
+
+## See Also
+
+- [How to use product categories in a storefront](../store/use-categories.mdx)
diff --git a/docs/content/modules/products/categories.md b/docs/content/modules/products/categories.md
index 5b0d97dc88..39184a636a 100644
--- a/docs/content/modules/products/categories.md
+++ b/docs/content/modules/products/categories.md
@@ -91,4 +91,5 @@ Aside from these relations, the `mpath` attribute, which is a [Materialized Path
 
 ## See Also
 
-- [How to manage product categories using the admin APIs](./admin/manage-categories.mdx)
\ No newline at end of file
+- [How to manage product categories using the admin APIs](./admin/manage-categories.mdx)
+- [How to use product categories in a storefront](./store/use-categories.mdx)
diff --git a/docs/content/modules/products/overview.mdx b/docs/content/modules/products/overview.mdx
index 8243a39358..e7b98b759d 100644
--- a/docs/content/modules/products/overview.mdx
+++ b/docs/content/modules/products/overview.mdx
@@ -80,12 +80,11 @@ Customers can use this organization to filter products while browsing them.
   },
   {
     type: 'link',
-    href: '#',
+    href: '/modules/products/store/use-categories',
     label: 'Storefront: Use Categories',
     customProps: {
       icon: Icons['server-solid'],
       description: 'Learn how to use categories in a storefront.',
-      isSoon: true,
     }
   },
 ]} />
diff --git a/docs/content/modules/products/store/use-categories.mdx b/docs/content/modules/products/store/use-categories.mdx
new file mode 100644
index 0000000000..c324fab099
--- /dev/null
+++ b/docs/content/modules/products/store/use-categories.mdx
@@ -0,0 +1,167 @@
+---
+description: 'Learn how to use product categories in your storefront using the REST APIs. This includes listing categories and retrieving a single category.'
+addHowToData: true
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# How to Use Product Categories in a Storefront
+
+In this document, you’ll learn how to use product categories in a storefront.
+
+## Overview
+
+Using the product category store REST APIs, you can list categories in your storefront.
+
+### Scenario
+
+You want to add or use the following store functionalities:
+
+- List and filter categories.
+- Retrieve a single category.
+
+---
+
+## Prerequisites
+
+### Medusa Components
+
+It's assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../../development/backend/install.mdx) to get started.
+
+It's also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install the [Next.js starter storefront](../../../starters/nextjs-medusa-starter.mdx).
+
+### JS Client
+
+This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.
+
+If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration).
+
+### Medusa React
+
+This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.
+
+If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage).
+
+---
+
+## List Categories
+
+You can list product categories by sending a request to the [List Product Categories endpoint](/api/store#tag/Product-Category/operation/GetProductCategories):
+
+```ts
+medusa.productCategories.list()
+.then(({ product_categories, limit, offset, count }) => {
+  console.log(product_categories.length)
+})
+```
+
+```tsx
+import { useProductCategories } from "medusa-react"
+import { ProductCategory } from "@medusajs/medusa"
+
+function Categories() {
+  const { 
+    product_categories, 
+    isLoading,
+  } = useProductCategories()
+
+  return (
+    <div>
+      {isLoading && <span>Loading...</span>}
+      {product_categories && !product_categories.length && (
+        <span>No Categories</span>
+      )}
+      {product_categories && product_categories.length > 0 && (
+        <ul>
+          {product_categories.map(
+            (category: ProductCategory) => (
+              <li key={category.id}>{category.name}</li>
+            )
+          )}
+        </ul>
+      )}
+    </div>
+  )
+}
+
+export default Categories
+```
+
+```ts
+fetch(`<BACKEND_URL>/product-categories`, {
+  credentials: "include",
+})
+.then((response) => response.json())
+.then(({ product_categories, limit, offset, count }) => {
+  console.log(product_categories.length)
+})
+```
+
+```bash
+curl -L -X GET '<BACKEND_URL>/store/product-categories' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+This request does not require any query parameters. You can, however, pass query parameters to filter the list of categories, such as the passing the `q` query parameter to search categories by title or handle. You can learn about available query parameters in the [API reference](/api/store#tag/Product-Category/operation/GetProductCategories).
+
+The request returns an array of product categories along with [pagination fields](/api/store#section/Pagination).
+
+### Including all Nested Categories
+
+By default, the categories are not retrieved along with their nested children. To retrieve categories with their nested children, make sure to pass the query parameter `include_descendants_tree` with the value `true`. Nested categories will be available inside each category object under the property `category_children`, which is an array of categories.
+
+---
+
+## Get a Category
+
+You can retrieve a single product category by using the [Get a Product Category endpoint](/api/store#tag/Product-Category/operation/GetProductCategoriesCategory):
+
+```ts
+medusa.productCategories.retrieve(productCategoryId)
+.then(({ product_category }) => {
+  console.log(product_category.name)
+})
+```
+
+```tsx
+import { useProductCategory } from "medusa-react"
+
+function Category() {
+  const { product_category, isLoading } = useProductCategory()
+
+  return (
+    <div>
+      {isLoading && <span>Loading...</span>}
+      {product_category && <span>{product_category.name}</span>}
+    </div>
+  )
+}
+
+export default Category
+```
+
+```ts
+fetch(`<BACKEND_URL>/product-categories/${productCategoryId}`, {
+  credentials: "include",
+})
+.then((response) => response.json())
+.then(({ product_category }) => {
+  console.log(product_category.name)
+})
+```
+
+```bash
+curl -L -X GET '<BACKEND_URL>/store/product-categories/<CAT_ID>' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+This request requires the product category ID as a path parameter. You can also pass query parameters such as `expand` and `fields` as explained in the [API reference](/api/store#tag/Product-Category/operation/GetProductCategoriesCategory).
+
+The request returns the category as an object.
+
+---
+
+## See Also
+
+- [How to manage product categories](../admin/manage-categories.mdx).
diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js
index fb98293ea7..b547b94cd9 100644
--- a/www/docs/sidebars.js
+++ b/www/docs/sidebars.js
@@ -630,6 +630,11 @@ module.exports = {
             sidebar_is_soon: true,
           },
         },
+        {
+          type: "doc",
+          id: "modules/products/store/use-categories",
+          label: "Storefront: Use Categories",
+        },
         {
           type: "link",
           href: "#",