docs: generate medusa-react reference (#6004)
* add new plugin for better organization * added handling in theme for mutations and query types * added tsdoc to hooks * added tsdocs to utility functions * added tsdoc to providers * generated reference * general fixes for generated reference * generated api reference specs + general fixes * add missing import react * split utilities into different directories * added overview page * added link to customer authentication section * fix lint errors * added changeset * fix readme * fixed build error * added expand fields + other sections to overview * updated what's new section * general refactoring * remove unnecessary query field * fix links * added ignoreApi option
This commit is contained in:
Shahed Nasser
@@ -1,17 +1,91 @@
|
||||
/**
|
||||
* @packageDocumentation
|
||||
*
|
||||
* `medusa-react` exposes a set of utility functions that are mainly used to retrieve or format the price of a product variant.
|
||||
*
|
||||
* @customNamespace Utilities
|
||||
*/
|
||||
|
||||
import { ProductVariantInfo, RegionInfo } from "../types"
|
||||
import { isEmpty } from "../utils"
|
||||
|
||||
type FormatVariantPriceParams = {
|
||||
/**
|
||||
* @interface
|
||||
*
|
||||
* Options to format a variant's price.
|
||||
*/
|
||||
export type FormatVariantPriceParams = {
|
||||
/**
|
||||
* A variant's details.
|
||||
*/
|
||||
variant: ProductVariantInfo
|
||||
/**
|
||||
* A region's details.
|
||||
*/
|
||||
region: RegionInfo
|
||||
/**
|
||||
* Whether the computed price should include taxes or not.
|
||||
*
|
||||
* @defaultValue true
|
||||
*/
|
||||
includeTaxes?: boolean
|
||||
/**
|
||||
* The minimum number of fraction digits to use when formatting the price. This is passed as an option to `Intl.NumberFormat` in the underlying layer.
|
||||
* You can learn more about this method’s options in
|
||||
* [MDN’s documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters).
|
||||
*/
|
||||
minimumFractionDigits?: number
|
||||
/**
|
||||
* The maximum number of fraction digits to use when formatting the price. This is passed as an option to `Intl.NumberFormat` which is used within the utility method.
|
||||
* You can learn more about this method’s options in
|
||||
* [MDN’s documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters).
|
||||
*/
|
||||
maximumFractionDigits?: number
|
||||
/**
|
||||
* A BCP 47 language tag. The default value is `en-US`. This is passed as a first parameter to `Intl.NumberFormat` which is used within the utility method.
|
||||
* You can learn more about this method’s parameters in
|
||||
* [MDN’s documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters).
|
||||
*/
|
||||
locale?: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Takes a product variant and a region, and converts the variant's price to a localized decimal format
|
||||
* This utility function can be used to compute the price of a variant for a region and retrieve the formatted amount. For example, `$20.00`.
|
||||
*
|
||||
* @param {FormatVariantPriceParams} param0 - Options to format the variant's price.
|
||||
* @returns {string} The formatted price.
|
||||
*
|
||||
* @example
|
||||
* ```tsx title="src/Products.ts"
|
||||
* import React from "react"
|
||||
* import { formatVariantPrice } from "medusa-react"
|
||||
* import { Product, ProductVariant } from "@medusajs/medusa"
|
||||
*
|
||||
* const Products = () => {
|
||||
* // ...
|
||||
* return (
|
||||
* <ul>
|
||||
* {products?.map((product: Product) => (
|
||||
* <li key={product.id}>
|
||||
* {product.title}
|
||||
* <ul>
|
||||
* {product.variants.map((variant: ProductVariant) => (
|
||||
* <li key={variant.id}>
|
||||
* {formatVariantPrice({
|
||||
* variant,
|
||||
* region, // should be retrieved earlier
|
||||
* })}
|
||||
* </li>
|
||||
* ))}
|
||||
* </ul>
|
||||
* </li>
|
||||
* ))}
|
||||
* </ul>
|
||||
* )
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @customNamespace Utilities
|
||||
*/
|
||||
export const formatVariantPrice = ({
|
||||
variant,
|
||||
@@ -28,17 +102,66 @@ export const formatVariantPrice = ({
|
||||
})
|
||||
}
|
||||
|
||||
type ComputeVariantPriceParams = {
|
||||
/**
|
||||
* @interface
|
||||
*
|
||||
* Options to format a variant's price.
|
||||
*/
|
||||
export type ComputeVariantPriceParams = {
|
||||
/**
|
||||
* A variant's details.
|
||||
*/
|
||||
variant: ProductVariantInfo
|
||||
/**
|
||||
* A region's details.
|
||||
*/
|
||||
region: RegionInfo
|
||||
/**
|
||||
* Whether the computed price should include taxes or not.
|
||||
*
|
||||
* @defaultValue true
|
||||
*/
|
||||
includeTaxes?: boolean
|
||||
}
|
||||
|
||||
/**
|
||||
* Takes a product variant and region, and returns the variant price as a decimal number
|
||||
* @param params.variant - product variant
|
||||
* @param params.region - region
|
||||
* @param params.includeTaxes - whether to include taxes or not
|
||||
* This utility function can be used to compute the price of a variant for a region and retrieve the amount without formatting.
|
||||
* For example, `20`. This method is used by {@link formatVariantPrice} before applying the price formatting.
|
||||
*
|
||||
* @param {ComputeVariantPriceParams} param0 - Options to compute the variant's price.
|
||||
* @returns The computed price of the variant.
|
||||
*
|
||||
* @example
|
||||
* ```tsx title="src/Products.ts"
|
||||
* import React from "react"
|
||||
* import { computeVariantPrice } from "medusa-react"
|
||||
* import { Product, ProductVariant } from "@medusajs/medusa"
|
||||
*
|
||||
* const Products = () => {
|
||||
* // ...
|
||||
* return (
|
||||
* <ul>
|
||||
* {products?.map((product: Product) => (
|
||||
* <li key={product.id}>
|
||||
* {product.title}
|
||||
* <ul>
|
||||
* {product.variants.map((variant: ProductVariant) => (
|
||||
* <li key={variant.id}>
|
||||
* {computeVariantPrice({
|
||||
* variant,
|
||||
* region, // should be retrieved earlier
|
||||
* })}
|
||||
* </li>
|
||||
* ))}
|
||||
* </ul>
|
||||
* </li>
|
||||
* ))}
|
||||
* </ul>
|
||||
* )
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @customNamespace Utilities
|
||||
*/
|
||||
export const computeVariantPrice = ({
|
||||
variant,
|
||||
@@ -55,10 +178,44 @@ export const computeVariantPrice = ({
|
||||
}
|
||||
|
||||
/**
|
||||
* Finds the price amount correspoding to the region selected
|
||||
* @param variant - the product variant
|
||||
* @param region - the region
|
||||
* @returns - the price's amount
|
||||
* This utility function is used to retrieve a variant's price in a region. It doesn't take into account taxes or any options, so you typically wouldn't need this function on its own.
|
||||
* It's used by the {@link computeVariantPrice} function to retrieve the variant's price in a region before computing the correct price for the options provided.
|
||||
*
|
||||
* @param {ProductVariantInfo} variant - The variant's details.
|
||||
* @param {RegionInfo} region - The region's details.
|
||||
* @returns {number} The variant's price in a region.
|
||||
*
|
||||
* @example
|
||||
* ```tsx title="src/Products.ts"
|
||||
* import React from "react"
|
||||
* import { getVariantPrice } from "medusa-react"
|
||||
* import { Product, ProductVariant } from "@medusajs/medusa"
|
||||
*
|
||||
* const Products = () => {
|
||||
* // ...
|
||||
* return (
|
||||
* <ul>
|
||||
* {products?.map((product: Product) => (
|
||||
* <li key={product.id}>
|
||||
* {product.title}
|
||||
* <ul>
|
||||
* {product.variants.map((variant: ProductVariant) => (
|
||||
* <li key={variant.id}>
|
||||
* {getVariantPrice(
|
||||
* variant,
|
||||
* region, // should be retrieved earlier
|
||||
* )}
|
||||
* </li>
|
||||
* ))}
|
||||
* </ul>
|
||||
* </li>
|
||||
* ))}
|
||||
* </ul>
|
||||
* )
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @customNamespace Utilities
|
||||
*/
|
||||
export const getVariantPrice = (
|
||||
variant: ProductVariantInfo,
|
||||
@@ -72,14 +229,54 @@ export const getVariantPrice = (
|
||||
return price?.amount || 0
|
||||
}
|
||||
|
||||
type ComputeAmountParams = {
|
||||
/**
|
||||
* Options to compute an amount.
|
||||
*/
|
||||
export type ComputeAmountParams = {
|
||||
/**
|
||||
* The original amount used for computation.
|
||||
*/
|
||||
amount: number
|
||||
/**
|
||||
* The region's details.
|
||||
*/
|
||||
region: RegionInfo
|
||||
/**
|
||||
* Whether the computed price should include taxes or not.
|
||||
*
|
||||
* @defaultValue true
|
||||
*/
|
||||
includeTaxes?: boolean
|
||||
}
|
||||
|
||||
/**
|
||||
* Takes an amount, a region, and returns the amount as a decimal including or excluding taxes
|
||||
* This utility function can be used to compute the price of an amount for a region and retrieve the amount without formatting. For example, `20`.
|
||||
* This function is used by {@link formatAmount} before applying the price formatting.
|
||||
*
|
||||
* The main difference between this utility function and {@link computeVariantPrice} is that you don’t need to pass a complete variant object. This can be used with any number.
|
||||
*
|
||||
* @param {ComputeAmountParams} params0 - The options to compute the amount.
|
||||
* @returns {number} The computed amount.
|
||||
*
|
||||
* @example
|
||||
* ```tsx title="src/MyComponent.ts"
|
||||
* import React from "react"
|
||||
* import { computeAmount } from "medusa-react"
|
||||
*
|
||||
* const MyComponent = () => {
|
||||
* // ...
|
||||
* return (
|
||||
* <div>
|
||||
* {computeAmount({
|
||||
* amount,
|
||||
* region, // should be retrieved earlier
|
||||
* })}
|
||||
* </div>
|
||||
* )
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @customNamespace Utilities
|
||||
*/
|
||||
export const computeAmount = ({
|
||||
amount,
|
||||
@@ -95,17 +292,81 @@ export const computeAmount = ({
|
||||
return amountWithTaxes
|
||||
}
|
||||
|
||||
type FormatAmountParams = {
|
||||
/**
|
||||
* Options to format an amount.
|
||||
*/
|
||||
export type FormatAmountParams = {
|
||||
/**
|
||||
* The original amount used for computation.
|
||||
*/
|
||||
amount: number
|
||||
/**
|
||||
* The region's details.
|
||||
*/
|
||||
region: RegionInfo
|
||||
/**
|
||||
* Whether the computed price should include taxes or not.
|
||||
*
|
||||
* @defaultValue true
|
||||
*/
|
||||
includeTaxes?: boolean
|
||||
/**
|
||||
* The minimum number of fraction digits to use when formatting the price. This is passed as an option to `Intl.NumberFormat` in the underlying layer.
|
||||
* You can learn more about this method’s options in
|
||||
* [MDN’s documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters).
|
||||
*/
|
||||
minimumFractionDigits?: number
|
||||
/**
|
||||
* The maximum number of fraction digits to use when formatting the price. This is passed as an option to `Intl.NumberFormat` which is used within the utility method.
|
||||
* You can learn more about this method’s options in
|
||||
* [MDN’s documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters).
|
||||
*/
|
||||
maximumFractionDigits?: number
|
||||
/**
|
||||
* A BCP 47 language tag. The default value is `en-US`. This is passed as a first parameter to `Intl.NumberFormat` which is used within the utility method.
|
||||
* You can learn more about this method’s parameters in
|
||||
* [MDN’s documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters).
|
||||
*/
|
||||
locale?: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Takes an amount and a region, and converts the amount to a localized decimal format
|
||||
* This utility function can be used to compute the price of an amount for a region and retrieve the formatted amount. For example, `$20.00`.
|
||||
*
|
||||
* The main difference between this utility function and {@link formatVariantPrice} is that you don’t need to pass a complete variant object. This can be used with any number.
|
||||
*
|
||||
* @param {FormatAmountParams} param0 - Options to format the amount.
|
||||
* @returns {string} The formatted price.
|
||||
*
|
||||
* @example
|
||||
* import React from "react"
|
||||
* import { formatVariantPrice } from "medusa-react"
|
||||
* import { Product, ProductVariant } from "@medusajs/medusa"
|
||||
*
|
||||
* const Products = () => {
|
||||
* // ...
|
||||
* return (
|
||||
* <ul>
|
||||
* {products?.map((product: Product) => (
|
||||
* <li key={product.id}>
|
||||
* {product.title}
|
||||
* <ul>
|
||||
* {product.variants.map((variant: ProductVariant) => (
|
||||
* <li key={variant.id}>
|
||||
* {formatVariantPrice({
|
||||
* variant,
|
||||
* region, // should be retrieved earlier
|
||||
* })}
|
||||
* </li>
|
||||
* ))}
|
||||
* </ul>
|
||||
* </li>
|
||||
* ))}
|
||||
* </ul>
|
||||
* )
|
||||
* }
|
||||
*
|
||||
* @customNamespace Utilities
|
||||
*/
|
||||
export const formatAmount = ({
|
||||
amount,
|
||||
@@ -166,3 +427,8 @@ type ConvertToLocaleParams = {
|
||||
maximumFractionDigits?: number
|
||||
locale?: string
|
||||
}
|
||||
|
||||
/**
|
||||
* @internal We need to export these types so that they're included in the generated reference documentation.
|
||||
*/
|
||||
export { ProductVariantInfo, RegionInfo }
|
||||
Reference in New Issue
Block a user