@vendure/docs 0.0.0-202601161541

package/docs/guides/storefront/navigation-menu/index.mdx

@@ -0,0 +1,157 @@
+---
+title: "Navigation Menu"
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Stackblitz from '@site/src/components/Stackblitz';
+
+A navigation menu allows your customers to navigate your store and find the products they are looking for.
+
+Typically, navigation is based on a hierarchy of [collections](/guides/core-concepts/collections/). We can get the top-level
+collections using the `collections` query with the `topLevelOnly` filter:
+
+
+<Tabs>
+<TabItem value="Query" label="Query" default>
+
+```graphql
+query GetTopLevelCollections {
+  collections(options: { topLevelOnly: true }) {
+    items {
+      id
+      slug
+      name
+      featuredAsset {
+        id
+        preview
+      }
+    }
+  }
+}
+```
+
+</TabItem>
+<TabItem value="Response" label="Response" >
+
+```json
+{
+  "data": {
+    "collections": {
+      "items": [
+        {
+          "id": "2",
+          "slug": "electronics",
+          "name": "Electronics",
+          "featuredAsset": {
+            "id": "16",
+            "preview": "https://demo.vendure.io/assets/preview/5b/jakob-owens-274337-unsplash__preview.jpg"
+          }
+        },
+        {
+          "id": "5",
+          "slug": "home-garden",
+          "name": "Home & Garden",
+          "featuredAsset": {
+            "id": "47",
+            "preview": "https://demo.vendure.io/assets/preview/3e/paul-weaver-1120584-unsplash__preview.jpg"
+          }
+        },
+        {
+          "id": "8",
+          "slug": "sports-outdoor",
+          "name": "Sports & Outdoor",
+          "featuredAsset": {
+            "id": "24",
+            "preview": "https://demo.vendure.io/assets/preview/96/michael-guite-571169-unsplash__preview.jpg"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Building a navigation tree
+
+The `collections` query returns a flat list of collections, but we often want to display them in a tree-like structure.
+This way, we can build up a navigation menu which reflects the hierarchy of collections.
+
+First of all we need to ensure that we have the `parentId` property on each collection.
+
+```graphql title="Shop API"
+query GetAllCollections {
+  collections(options: { topLevelOnly: true }) {
+    items {
+      id
+      slug
+      name
+      // highlight-next-line
+      parentId
+      featuredAsset {
+        id
+        preview
+      }
+    }
+  }
+}
+```
+
+Then we can use this data to build up a tree structure. The following code snippet shows how this can be done in TypeScript:
+
+```ts title="src/utils/array-to-tree.ts"
+export type HasParent = { id: string; parentId: string | null };
+export type TreeNode<T extends HasParent> = T & {
+    children: Array<TreeNode<T>>;
+};
+export type RootNode<T extends HasParent> = {
+    id?: string;
+    children: Array<TreeNode<T>>;
+};
+
+/**
+ * Builds a tree from an array of nodes which have a parent.
+ * Based on https://stackoverflow.com/a/31247960/772859, modified to preserve ordering.
+ */
+export function arrayToTree<T extends HasParent>(nodes: T[]): RootNode<T> {
+    const topLevelNodes: Array<TreeNode<T>> = [];
+    const mappedArr: { [id: string]: TreeNode<T> } = {};
+
+    // First map the nodes of the array to an object -> create a hash table.
+    for (const node of nodes) {
+        mappedArr[node.id] = { ...(node as any), children: [] };
+    }
+
+    for (const id of nodes.map((n) => n.id)) {
+        if (mappedArr.hasOwnProperty(id)) {
+            const mappedElem = mappedArr[id];
+            const parentId = mappedElem.parentId;
+            if (!parent) {
+                continue;
+            }
+            // If the element is not at the root level, add it to its parent array of children.
+            const parentIsRoot = !mappedArr[parentId];
+            if (!parentIsRoot) {
+                if (mappedArr[parentId]) {
+                    mappedArr[parentId].children.push(mappedElem);
+                } else {
+                    mappedArr[parentId] = { children: [mappedElem] } as any;
+                }
+            } else {
+                topLevelNodes.push(mappedElem);
+            }
+        }
+    }
+    const rootId = topLevelNodes.length ? topLevelNodes[0].parentId : undefined;
+    return { id: rootId, children: topLevelNodes };
+}
+```
+
+## Live example
+
+Here's a live demo of the above code in action:
+
+<Stackblitz id='vendure-docs-collection-tree' />

package/docs/guides/storefront/order-workflow/index.md

@@ -0,0 +1,231 @@
+---
+title: "Order Workflow"
+showtoc: true
+---
+
+# Order Workflow
+
+An Order is a collection of one or more ProductVariants which can be purchased by a Customer. Orders are represented internally by the [Order entity](/reference/typescript-api/entities/order/) and in the GraphQL API by the [Order type](/reference/graphql-api/admin/enums/#ordertype).
+
+## Order State
+
+Every Order has a `state` property of type [`OrderState`](/reference/typescript-api/orders/order-process/#orderstate). The following diagram shows the default states and how an Order transitions from one to the next.
+
+:::note
+Note that this default workflow can be modified to better fit your business processes. See the [Customizing the Order Process guide](/guides/core-concepts/orders/#custom-order-processes).
+:::
+
+![./order_state_diagram.png](./order_state_diagram.png)
+
+## Structure of an Order
+
+In Vendure an [Order](/reference/typescript-api/entities/order) consists of one or more [OrderLines](/reference/typescript-api/entities/order-line) (representing a given quantity of a particular SKU).
+
+Here is a simplified diagram illustrating this relationship:
+
+![./order_class_diagram.png](./order_class_diagram.png)
+
+## Shop client order workflow
+
+The [GraphQL Shop API Guide](/guides/storefront/active-order) lists the GraphQL operations you will need to implement this workflow in your storefront client application.
+
+In this section, we'll cover some examples of how these operations would look in your storefront.
+
+### Manipulating the Order
+
+First, let's define a fragment for our Order that we can re-use in subsequent operations:
+
+```graphql
+fragment ActiveOrder on Order {
+  id
+  code
+  state
+  couponCodes
+  subTotalWithTax
+  shippingWithTax
+  totalWithTax
+  totalQuantity
+  lines {
+    id
+    productVariant {
+      id
+      name
+    }
+    featuredAsset {
+      id
+      preview
+    }
+    quantity
+    linePriceWithTax
+  }
+}
+```
+
+Then we can add an item to the Order:
+
+```graphql
+mutation AddItemToOrder($productVariantId: ID! $quantity: Int!){
+  addItemToOrder(productVariantId: $productVariantId, quantity: $quantity) {
+    ... ActiveOrder
+    ... on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+To remove an item from the order
+
+```graphql
+mutation RemoveItemFromOrder($orderLineId: ID!){
+  removeOrderLine(orderLineId: $orderLineId) {
+    ... ActiveOrder
+    ... on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+To alter the quantity of an existing OrderLine
+
+```graphql
+mutation AdjustOrderLine($orderLineId: ID! $quantity: Int!){
+  adjustOrderLine(orderLineId: $orderLineId, quantity: $quantity) {
+    ... ActiveOrder
+    ... on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+At any time we can query the contents of the active Order:
+
+```graphql
+query ActiveOrder {
+  activeOrder {
+    ... ActiveOrder
+  }  
+}
+```
+
+### Checking out
+
+During the checkout process, we'll need to make sure a Customer is assigned to the Order. If the Customer is already signed in, then this can be skipped since Vendure will have already assigned them. If not, then you'd execute:
+
+```graphql
+mutation SetCustomerForOrder($input: CreateCustomerInput!){
+  setCustomerForOrder(input: $input) {
+    ... ActiveOrder
+    ... on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+Then we need to set the shipping address:
+
+```graphql
+mutation SetShippingAddress($input: CreateAddressInput!){
+  setOrderShippingAddress(input: $input) {
+    ... ActiveOrder
+    ... on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+Once the shipping address is set, we can find out which ShippingMethods can be used on this Order:
+
+```graphql
+query GetShippingMethods{
+  eligibleShippingMethods {
+    id
+    name
+    code
+    description
+    priceWithTax
+  }
+}
+```
+
+The Customer can then choose one of the available ShippingMethods, and we then set it on the Order:
+
+```graphql
+mutation SetShippingMethod($shippingMethodId: ID!){
+  setOrderShippingMethod(shippingMethodId: $shippingMethodId) {
+    ... ActiveOrder
+    ... on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+We can now do the same for PaymentMethods:
+
+```graphql
+query GetPaymentMethods{
+  eligiblePaymentMethods {
+    id
+    name
+    code
+    description
+    isEligible
+    eligibilityMessage
+  }
+}
+```
+
+Once the customer is ready to pay, we need to transition the Order to the `ArrangingPayment` state. In this state, no further modifications are permitted. If you _do_ need to modify the Order contents, you can always transition back to the `AddingItems` state:
+
+```graphql
+mutation TransitionOrder($state: String!){
+  transitionOrderToState(state: $state) {
+    ... ActiveOrder
+    ... on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+Finally, add a Payment to the Order:
+
+```graphql
+mutation AddPayment($input: PaymentInput!){
+  addPaymentToOrder(input: $input) {
+    ... ActiveOrder
+    ... on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+If the Payment is successful, the Order will now be complete. You can forward the Customer to a confirmation page using the Order's `code`:
+
+```graphql
+query OrderByCode($code: String!) {
+  orderByCode(code: $code) {
+    ...ActiveOrder
+  }
+}
+```
+
+## ActiveOrderStrategy
+
+In the above examples, the active Order is always associated with the current session and is therefore implicit - which is why there is no need to pass an ID to each of the above operations.
+
+Sometimes you _do_ want to be able to explicitly specify the Order you wish to operate on. In this case, you need to define a custom [ActiveOrderStrategy](/reference/typescript-api/orders/active-order-strategy).

package/docs/guides/storefront/product-detail/index.mdx

@@ -0,0 +1,295 @@
+---
+title: "Product Detail Page"
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Stackblitz from '@site/src/components/Stackblitz';
+
+The product detail page (often abbreviated to PDP) is the page that shows the details of a product and allows the user to add it to their cart.
+
+Typically, the PDP should include:
+
+- Product name
+- Product description
+- Available product variants
+- Images of the product and its variants
+- Price information
+- Stock information
+- Add to cart button
+
+## Fetching product data
+
+Let's create a query to fetch the required data. You should have either the product's `slug` or `id` available from the
+url. We'll use the `slug` in this example.
+
+<Tabs>
+<TabItem value="Query" label="Query" default>
+
+```graphql
+query GetProductDetail($slug: String!) {
+  product(slug: $slug) {
+    id
+    name
+    description
+    featuredAsset {
+      id
+      preview
+    }
+    assets {
+      id
+      preview
+    }
+    variants {
+      id
+      name
+      sku
+      stockLevel
+      currencyCode
+      price
+      priceWithTax
+      featuredAsset {
+        id
+        preview
+      }
+      assets {
+        id
+        preview
+      }
+    }
+  }
+}
+```
+
+</TabItem>
+<TabItem value="Variables" label="Variables">
+
+```json
+{
+  "slug": "laptop"
+}
+```
+
+</TabItem>
+<TabItem value="Response" label="Response" >
+
+```json
+{
+  "data": {
+    "product": {
+      "id": "1",
+      "name": "Laptop",
+      "description": "Now equipped with seventh-generation Intel Core processors, Laptop is snappier than ever. From daily tasks like launching apps and opening files to more advanced computing, you can power through your day thanks to faster SSDs and Turbo Boost processing up to 3.6GHz.",
+      "featuredAsset": {
+        "id": "1",
+        "preview": "https://demo.vendure.io/assets/preview/71/derick-david-409858-unsplash__preview.jpg"
+      },
+      "assets": [
+        {
+          "id": "1",
+          "preview": "https://demo.vendure.io/assets/preview/71/derick-david-409858-unsplash__preview.jpg"
+        }
+      ],
+      "variants": [
+        {
+          "id": "1",
+          "name": "Laptop 13 inch 8GB",
+          "sku": "L2201308",
+          "stockLevel": "IN_STOCK",
+          "currencyCode": "USD",
+          "price": 129900,
+          "priceWithTax": 155880,
+          "featuredAsset": null,
+          "assets": []
+        },
+        {
+          "id": "2",
+          "name": "Laptop 15 inch 8GB",
+          "sku": "L2201508",
+          "stockLevel": "IN_STOCK",
+          "currencyCode": "USD",
+          "price": 139900,
+          "priceWithTax": 167880,
+          "featuredAsset": null,
+          "assets": []
+        },
+        {
+          "id": "3",
+          "name": "Laptop 13 inch 16GB",
+          "sku": "L2201316",
+          "stockLevel": "IN_STOCK",
+          "currencyCode": "USD",
+          "price": 219900,
+          "priceWithTax": 263880,
+          "featuredAsset": null,
+          "assets": []
+        },
+        {
+          "id": "4",
+          "name": "Laptop 15 inch 16GB",
+          "sku": "L2201516",
+          "stockLevel": "IN_STOCK",
+          "currencyCode": "USD",
+          "price": 229900,
+          "priceWithTax": 275880,
+          "featuredAsset": null,
+          "assets": []
+        }
+      ]
+    }
+  }
+}
+```
+
+
+</TabItem>
+</Tabs>
+
+This single query provides all the data we need to display our PDP.
+
+## Formatting prices
+
+As explained in the [Money & Currency guide](/guides/core-concepts/money/), the prices are returned as integers in the
+smallest unit of the currency (e.g. cents for USD). Therefore, when we display the price, we need to divide by 100 and
+format it according to the currency's formatting rules.
+
+In the demo at the end of this guide, we'll use the [`formatCurrency` function](/guides/core-concepts/money/#displaying-monetary-values)
+which makes use of the browser's `Intl` API to format the price according to the user's locale.
+
+## Displaying images
+
+If we are using the [`AssetServerPlugin`](/reference/core-plugins/asset-server-plugin/) to serve our product images (as is the default), then we can take advantage
+of the dynamic image transformation abilities in order to display the product images in the correct size and in
+and optimized format such as WebP.
+
+This is done by appending a query string to the image URL. For example, if we want to use the `'large'` size preset (800 x 800)
+and convert the format to WebP, we'd use a url like this:
+
+```tsx
+<img src={product.featuredAsset.preview + '?preset=large&format=webp'} />
+```
+
+An even more sophisticated approach would be to make use of the HTML [`<picture>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture) to provide multiple image sources
+so that the browser can select the optimal format. This can be wrapped in a component to make it easier to use. For example:
+
+```tsx title="src/components/VendureAsset.tsx"
+interface VendureAssetProps {
+    preview: string;
+    preset: 'tiny' | 'thumb' | 'small' | 'medium' | 'large';
+    alt: string;
+}
+
+export function VendureAsset({ preview, preset, alt }: VendureAssetProps) {
+    return (
+        <picture>
+            <source type="image/avif" srcSet={preview + `?preset=${preset}&format=avif`} />
+            <source type="image/webp" srcSet={preview + `?preset=${preset}&format=webp`} />
+            <img src={preview + `?preset=${preset}&format=jpg`} alt={alt} />
+        </picture>
+    );
+}
+```
+
+## Adding to the order
+
+To add a particular product variant to the order, we need to call the [`addItemToOrder`](/reference/graphql-api/shop/mutations/#additemtoorder) mutation.
+This mutation takes the `productVariantId` and the `quantity` as arguments.
+
+
+<Tabs>
+<TabItem value="Mutation" label="Mutation" default>
+
+```graphql
+mutation AddItemToOrder($variantId: ID!, $quantity: Int!) {
+  addItemToOrder(productVariantId: $variantId, quantity: $quantity) {
+    __typename
+    ...UpdatedOrder
+    ... on ErrorResult {
+      errorCode
+      message
+    }
+    ... on InsufficientStockError {
+      quantityAvailable
+      order {
+        ...UpdatedOrder
+      }
+    }
+  }
+}
+
+fragment UpdatedOrder on Order {
+  id
+  code
+  state
+  totalQuantity
+  totalWithTax
+  currencyCode
+  lines {
+    id
+    unitPriceWithTax
+    quantity
+    linePriceWithTax
+    productVariant {
+      id
+      name
+    }
+  }
+}
+```
+
+</TabItem>
+<TabItem value="Variables" label="Variables">
+
+```json
+{
+  "variantId": "4",
+  "quantity": 1
+}
+```
+
+</TabItem>
+<TabItem value="Response" label="Response" >
+
+```json
+{
+  "data": {
+    "addItemToOrder": {
+      "__typename": "Order",
+      "id": "5",
+      "code": "KE5FJPVV3Y3LX134",
+      "state": "AddingItems",
+      "totalQuantity": 1,
+      "totalWithTax": 275880,
+      "lines": [
+        {
+          "id": "14",
+          "unitPriceWithTax": 275880,
+          "quantity": 1,
+          "linePriceWithTax": 275880
+        }
+      ]
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+There are some important things to note about this mutation:
+
+- Because the `addItemToOrder` mutation returns a union type, we need to use a [fragment](/guides/getting-started/graphql-intro/#fragments) to specify the fields we want to return.
+In this case we have defined a fragment called `UpdatedOrder` which contains the fields we are interested in.
+- If any [expected errors](/guides/developer-guide/error-handling/) occur, the mutation will return an `ErrorResult` object. We'll be able to
+see the `errorCode` and `message` fields in the response, so that we can display a meaningful error message to the user.
+- In the special case of the `InsufficientStockError`, in addition to the `errorCode` and `message` fields, we also get the `quantityAvailable` field
+which tells us how many of the requested quantity are available (and have been added to the order). This is useful information to display to the user.
+The `InsufficientStockError` object also embeds the updated `Order` object, which we can use to update the UI.
+- The `__typename` field can be used by the client to determine which type of object has been returned. Its value will equal the name
+of the returned type. This means that we can check whether `__typename === 'Order'` in order to determine whether the mutation was successful.
+
+## Live example
+
+Here's an example that brings together all of the above concepts:
+
+<Stackblitz id="vendure-docs-product-detail" />