diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 6c2542e83..6e9157fa9 100755 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -93,41 +93,41 @@ module.exports = { { title: 'Composables', children: [ - ['/api-reference/magento-theme.useaddresses', 'useAddresses()'], - ['/api-reference/magento-theme.useapi', 'useApi()'], - ['/api-reference/magento-theme.usebilling', 'useBilling()'], - ['/api-reference/magento-theme.usecart', 'useCart()'], - ['/api-reference/magento-theme.usecategory', 'useCategory()'], - ['/api-reference/magento-theme.usecategorysearch', 'useCategorySearch()'], - ['/api-reference/magento-theme.useconfig', 'useConfig()'], - ['/api-reference/magento-theme.usecontent', 'useContent()'], - ['/api-reference/magento-theme.usecountrysearch', 'useCountrySearch()'], - ['/api-reference/magento-theme.usecurrency', 'useCurrency()'], - ['/api-reference/magento-theme.useexternalcheckout', 'useExternalCheckout()'], - ['/api-reference/magento-theme.usefacet', 'useFacet()'], - ['/api-reference/magento-theme.useforgotpassword', 'useForgotPassword()'], - ['/api-reference/magento-theme.usegetshippingmethods', 'useGetShippingMethods()'], - ['/api-reference/magento-theme.useguestuser', 'useGuestUser()'], - ['/api-reference/magento-theme.useimage', 'useImage()'], - ['/api-reference/magento-theme.usemagentoconfiguration', 'useMagentoConfiguration()'], - ['/api-reference/magento-theme.usemakeorder', 'useMakeOrder()'], - ['/api-reference/magento-theme.usenewsletter', 'useNewsletter()'], - ['/api-reference/magento-theme.usepaymentprovider', 'usePaymentProvider()'], - ['/api-reference/magento-theme.useproduct', 'useProduct()'], - ['/api-reference/magento-theme.userelatedproducts', 'useRelatedProducts()'], - ['/api-reference/magento-theme.usereview', 'useReview()'], - ['/api-reference/magento-theme.useshipping', 'useShipping()'], - ['/api-reference/magento-theme.useshippingprovider', 'useShippingProvider()'], - ['/api-reference/magento-theme.usestore', 'useStore()'], - ['/api-reference/magento-theme.useuihelpers', 'useUiHelpers()'], - ['/api-reference/magento-theme.useuinotification', 'useUiNotification()'], - ['/api-reference/magento-theme.useuistate', 'useUiState()'], - ['/api-reference/magento-theme.useupsellproducts', 'useUpsellProducts()'], - ['/api-reference/magento-theme.useurlresolver', 'useUrlResolver()'], - ['/api-reference/magento-theme.useuser', 'useUser()'], - ['/api-reference/magento-theme.useuseraddress', 'useUserAddress()'], - ['/api-reference/magento-theme.useuserorder', 'useUserOrder()'], - ['/api-reference/magento-theme.usewishlist', 'useWishlist()'], + ['/api-reference/magento-theme.useaddresses', 'useAddresses'], + ['/api-reference/magento-theme.useapi', 'useApi'], + ['/api-reference/magento-theme.usebilling', 'useBilling'], + ['/api-reference/magento-theme.usecart', 'useCart [Deprecated]'], + ['/api-reference/magento-theme.usecategory', 'useCategory [Deprecated]'], + ['/api-reference/magento-theme.usecategorysearch', 'useCategorySearch'], + ['/api-reference/magento-theme.useconfig', 'useConfig'], + ['/api-reference/magento-theme.usecontent', 'useContent'], + ['/api-reference/magento-theme.usecountrysearch', 'useCountrySearch'], + ['/api-reference/magento-theme.usecurrency', 'useCurrency'], + ['/api-reference/magento-theme.useexternalcheckout', 'useExternalCheckout'], + ['/api-reference/magento-theme.usefacet', 'useFacet [Deprecated]'], + ['/api-reference/magento-theme.useforgotpassword', 'useForgotPassword [Deprecated]'], + ['/api-reference/magento-theme.usegetshippingmethods', 'useGetShippingMethods [Deprecated]'], + ['/api-reference/magento-theme.useguestuser', 'useGuestUser [Deprecated]'], + ['/api-reference/magento-theme.useimage', 'useImage'], + ['/api-reference/magento-theme.usemagentoconfiguration', 'useMagentoConfiguration'], + ['/api-reference/magento-theme.usemakeorder', 'useMakeOrder [Deprecated]'], + ['/api-reference/magento-theme.usenewsletter', 'useNewsletter'], + ['/api-reference/magento-theme.usepaymentprovider', 'usePaymentProvider [Deprecated]'], + ['/api-reference/magento-theme.useproduct', 'useProduct [Deprecated]'], + ['/api-reference/magento-theme.userelatedproducts', 'useRelatedProducts [Deprecated]'], + ['/api-reference/magento-theme.usereview', 'useReview'], + ['/api-reference/magento-theme.useshipping', 'useShipping [Deprecated]'], + ['/api-reference/magento-theme.useshippingprovider', 'useShippingProvider'], + ['/api-reference/magento-theme.usestore', 'useStore'], + ['/api-reference/magento-theme.useuihelpers', 'useUiHelpers'], + ['/api-reference/magento-theme.useuinotification', 'useUiNotification'], + ['/api-reference/magento-theme.useuistate', 'useUiState'], + ['/api-reference/magento-theme.useupsellproducts', 'useUpsellProducts [Deprecated]'], + ['/api-reference/magento-theme.useurlresolver', 'useUrlResolver'], + ['/api-reference/magento-theme.useuser', 'useUser [Deprecated]'], + ['/api-reference/magento-theme.useuseraddress', 'useUserAddress'], + ['/api-reference/magento-theme.useuserorder', 'useUserOrder [Deprecated]'], + ['/api-reference/magento-theme.usewishlist', 'useWishlist [Deprecated]'], ], }, { diff --git a/packages/theme/composables/useApi/index.ts b/packages/theme/composables/useApi/index.ts index 48cdf4e17..9f8393e56 100644 --- a/packages/theme/composables/useApi/index.ts +++ b/packages/theme/composables/useApi/index.ts @@ -1,20 +1,58 @@ import { useContext } from '@nuxtjs/composition-api'; import type { Variables } from 'graphql-request'; -type Request = ( +export type Request = ( document: string, variables?: VARIABLES, requestHeaders?: HeadersInit ) => Promise; -/** The interface provided by {@link useApi} composable. */ +/** + * Methods returned by the {@link useApi|useApi()} composable. + */ export interface UseApiInterface { /** - * Executes received GraphQL Query with optional variables and headers and + * Executes received GraphQL query with optional variables and headers and * returns the result. + * + * @example + * + * Execute a GraphQL query and handle its error, loading and result: + * + * ```ts + * import { useApi } from '~/composables/useApi'; + * + * const GET_CART_PRICE_QUERY = ` + * query GET_CART_PRICE_QUERY($cartId: String!) { + * cart(cart_id: $cartId) { + * prices { + * subtotal_excluding_tax { + * value + * } + * } + * } + * } + * `; + * + * export default { + * setup() { + * const { query } = useApi(); + * + * async function getCartPrice(cartId: string) { + * return await query( + * GET_CART_PRICE_QUERY, + * { cartId }, + * { 'Accept': 'application/json' } + * ); + * } + * } + * }; + * ``` */ query: Request; + // TODO: Add code sample + /** * Executes received GraphQL Mutation with optional variables and headers and * returns the result. @@ -24,76 +62,6 @@ export interface UseApiInterface { /** * The `useApi()` composable allows executing GraphQL queries and mutations. - * - * @example - * - * Execute a GraphQL Query and handle its error, loading and result: - * - * ```ts - * import { ref, readonly } from '@nuxtjs/composition-api'; - * import { useApi } from '~/composables/useApi'; - * - * type GetCartPriceQueryVariables = { cartId: string }; - * - * type GetCartPriceQueryData = { - * cart: { - * prices: { - * subtotal_excluding_tax: { - * value: number; - * }; - * }[]; - * }; - * }; - * - * const GET_CART_PRICE_QUERY = ` - * query GET_CART_PRICE_QUERY($cartId: String!) { - * cart(cart_id: $cartId) { - * prices { - * subtotal_excluding_tax { - * value - * } - * } - * } - * } - * `; - * - * export default { - * setup() { - * const { query } = useApi(); - * - * const price = ref(null); - * const loading = ref(false); - * const error = ref(null); - * - * const getCartPrice = async (cartId: string) => { - * loading.value = false; - * try { - * const result = await query< - * GetCartPriceQueryData, - * GetCartPriceQueryVariables, - * >(GET_CART_PRICE_QUERY, { cartId }, { - * 'Accept': 'application/json', - * }); - * - * price.value = result.cart?.prices?.subtotal_excluding_tax?.value ?? null; - * error.value = null; - * } catch (error) { - * price.value = null; - * error.value = error; - * } finally { - * loading.value = false; - * } - * }; - * - * return { - * price: readonly(price), - * error: readonly(error), - * loading: readonly(loading), - * getCartPrice, - * }; - * }, - * }; - * ``` */ export function useApi(): UseApiInterface { const context = useContext(); diff --git a/packages/theme/composables/useConfig/index.ts b/packages/theme/composables/useConfig/index.ts index ab74800de..c94c0d43d 100644 --- a/packages/theme/composables/useConfig/index.ts +++ b/packages/theme/composables/useConfig/index.ts @@ -6,9 +6,9 @@ import { useConfigStore } from '~/stores/config'; import { UseConfigErrors, UseConfigInterface } from './useConfig'; /** - * The `useConfig` composable is responsible for interactions with the configuration in your eCommerce. + * The `useConfig` composable allows interacting with the store configuration. * - * See the {@link UseConfigInterface} page for more information. + * See the {@link UseConfigInterface} for a list of methods and values available in this composable. */ export function useConfig(): UseConfigInterface { const { app } = useContext(); diff --git a/packages/theme/composables/useConfig/useConfig.ts b/packages/theme/composables/useConfig/useConfig.ts index 057a38dd0..76f1700e5 100644 --- a/packages/theme/composables/useConfig/useConfig.ts +++ b/packages/theme/composables/useConfig/useConfig.ts @@ -1,20 +1,32 @@ import { ComputedRef, DeepReadonly, Ref } from '@nuxtjs/composition-api'; import { StoreConfig } from '~/modules/GraphQL/types'; -/** Errors returned by the {@link useConfig} composable */ +/** + * Errors that occured in the {@link useConfig|useConfig()} composable + */ export interface UseConfigErrors { - /** Error when loading configuration fails, otherwise is `null` */ + /** + * Contains error if `load` method failed, otherwise is `null` + */ load: Error | null; } /** - * Represents the data and methods returned by the {@link useConfig} composable + * The refs and methods returned by the {@link useConfig|useConfig()} composable */ export interface UseConfigInterface { - /** Returns the loaded config as computed property */ + /** + * Store configuration loaded using the `load` method + */ config: ComputedRef, - /** Return state of loadConfig Function as computed property */ + + /** + * Indicates whether any of the methods is in progress + */ loading: DeepReadonly>, - /** Function to load the config */ - load (): Promise + + /** + * Loads store configuration + */ + load(): Promise } diff --git a/packages/theme/composables/useContent/index.ts b/packages/theme/composables/useContent/index.ts index 33f030f2a..12b19a1e9 100644 --- a/packages/theme/composables/useContent/index.ts +++ b/packages/theme/composables/useContent/index.ts @@ -8,83 +8,9 @@ import type { ComposableFunctionArgs } from '../types'; import type { UseContentInterface, UseContentErrors } from './useContent'; /** - * @public * The `useContent` composable allows loading CMS Pages or Blocks from Magento API. * - * @remarks - * Under the hood, it calls the following Server Middleware API methods: - * - * - {@link @vue-storefront/magento-api#cmsBlocks} for loading CMS blocks - * - * - {@link @vue-storefront/magento-api#cmsPage} for loading CMS pages - * - * It is currently used in: - * - * - `components/ContentBlocks.vue` - * - * - `pages/Page.vue` - * - * @example - * Initialization in component: - * - * ```typescript - * import { useContent } from '~/composables'; - * - * export default { - * setup() { - * const { loading, error, loadPage, loadBlocks } = useContent(); - * } - * } - * ``` - * - * @example - * Load CMS Page: - * - * ```typescript - * import { useFetch } from '@nuxtjs/composition-api'; - * import { useContent } from '~/composables'; - * - * export default { - * setup() { - * const { loading, error, loadPage } = useContent(); - * - * const page = ref({}); - * const pageId = 'about-us' - * - * useFetch(async () => { - * page.value = await loadPage({ identifier: pageId }); - * - * if (error?.value?.page || !page.value) { - * // place for handle 404 error - * } - * }); - * } - * } - * ``` - * More example with loading CMS Page: {@link UseContentInterface.loadPage}. - * - * @example - * Load CMS Block: - * - * ```typescript - * import { useFetch, ref } from '@nuxtjs/composition-api'; - * import { useContent } from '~/composables'; - * - * export default { - * setup(props) { - * const { loadBlocks } = useContent(); - * const blocks = ref([]); - * - * useFetch(async () => { - * if (props.identifiers) { - * blocks.value = await loadBlocks(['block-a', 'block-b`]); - * } - * }); - * } - * } - * ``` - * - * More example with loading CMS Page: {@link UseContentInterface.loadBlocks}. + * See the {@link UseContentInterface} for a list of methods and values available in this composable. */ export function useContent(): UseContentInterface { const loading: Ref = ref(false); diff --git a/packages/theme/composables/useContent/useContent.ts b/packages/theme/composables/useContent/useContent.ts index 45000ead0..6d03dd786 100644 --- a/packages/theme/composables/useContent/useContent.ts +++ b/packages/theme/composables/useContent/useContent.ts @@ -2,37 +2,47 @@ import type { DeepReadonly, Ref } from '@nuxtjs/composition-api'; import type { CmsPage, CmsBlock } from '~/modules/GraphQL/types'; import type { ComposableFunctionArgs } from '../types'; +/** + * Errors that occured in the {@link useContent|useContent()} composable + */ export interface UseContentErrors { /** - * Errors related to CMS page loading + * Contains error if `loadPage` method failed, otherwise is `null` */ - page: Error; + page: Error | null; + /** - * Errors related to CMS blocks loading + * Contains error if `loadBlocks` method failed, otherwise is `null` */ - blocks: Error; + blocks: Error | null; } /** - * `UseContentInterface` is used by useContent composable, and it's responsible for fetching CMS data from Magento. + * The refs and methods returned by the {@link useContent|useContent()} composable */ export interface UseContentInterface { /** - * Loading state. It returns true when loading data from Magento is in progress + * Indicates whether any of the methods is in progress */ loading: DeepReadonly>; /** - * Contains errors from any of the methods. + * Contains errors from the composable methods */ error: DeepReadonly>; + /** - * Load CMS Page from Magento + * Loads CMS page + * + * @remarks * - * Returns Promise with {@link CmsPage} + * Internally, it calls the {@link @vue-storefront/magento-api#cmsPage} API endpoint + * and accepts custom query named `cmsPage`. * * @example - * Load CMS Page using the useFetch composition-api hook: + * + * Load CMS Page using the useFetch hook: + * * ```typescript * import { useFetch, ref } from '@nuxtjs/composition-api'; * import { useContent } from '~/composables'; @@ -48,112 +58,29 @@ export interface UseContentInterface { * page.value = await loadPage({ identifier: pageId }); * * if (error?.value?.page || !page.value) { - * // place for handle 404 error - * } - * }); - * } - * } - * ``` - * - * @example - * Load CMS Page using the useAsync Composition API hook: - * ```typescript - * import { useAsync } from '@nuxtjs/composition-api'; - * import { useContent } from '~/composables'; - * - * export default { - * setup() { - * const { loadPage } = useContent(); - * const pageId = 'about-us' - * - * const page = useAsync(async () => { - * const pageData = await loadPage({ identifier: pageId }); - * - * if (!pageData.value) { - * // place for handle 404 error - * } - * - * return pageData; - * }); - * } - * } - * ``` - * - * @example - * Load CMS Page on client side using the onMounted Composition API hook: - * ```typescript - * import { onMounted, ref } from '@nuxtjs/composition-api'; - * import { useContent } from '~/composables'; - * - * export default { - * setup() { - * const { loadPage } = useContent(); - * const page = ref({}); - * const pageId = 'about-us' - * - * onMounted(async () => { - * pageData.value = await loadPage({ identifier: pageId }); - * - * if (!pageData.value) { - * // place for handle 404 error + * // Handle error * } * }); * } * } * ``` */ - loadPage: (params: ComposableFunctionArgs<{ identifier: string }>) => Promise; + loadPage(params: ComposableFunctionArgs<{ identifier: string }>): Promise; /** - * Load CMS block from Magento - * - * Returns Promise with array of {@link CmsBlock} + * Loads CMS block * - * @example - * Load CMS Block on server side using the useFetch Composition API hook: - * ```typescript - * import { useFetch, ref } from '@nuxtjs/composition-api'; - * import { useContent } from '~/composables'; - * - * export default { - * setup(props) { - * const { loadBlocks } = useContent(); - * const blocks = ref([]); + * @remarks * - * useFetch(async () => { - * if (props.identifiers) { - * blocks.value = await loadBlocks(['block-a', 'block-b`]); - * } - * }); - * } - * } - * ``` + * Internally, it calls the {@link @vue-storefront/magento-api#cmsBlocks} API endpoint + * and accepts custom query named `cmsBlocks`. * * @example - * Load CMS Block on server side using the useAsync Composition API hook: - * ```typescript - * import { useAsync } from '@nuxtjs/composition-api'; - * import { useContent } from '~/composables'; - * - * export default { - * setup(props) { - * const { loadBlocks } = useContent(); - * - * const blocks = useAsync(async () => { - * if (props.identifiers) { - * return await loadBlocks(['block-a', 'block-b`]); - * } * - * return null; - * }); - * } - * } - * ``` + * Load CMS Block using the useFetch hook: * - * @example - * Load CMS Block on client side using the onMounted Composition API hook: * ```typescript - * import { onMounted, ref } from '@nuxtjs/composition-api'; + * import { useFetch, ref } from '@nuxtjs/composition-api'; * import { useContent } from '~/composables'; * * export default { @@ -161,7 +88,7 @@ export interface UseContentInterface { * const { loadBlocks } = useContent(); * const blocks = ref([]); * - * onMounted(async () => { + * useFetch(async () => { * if (props.identifiers) { * blocks.value = await loadBlocks(['block-a', 'block-b`]); * } @@ -170,5 +97,5 @@ export interface UseContentInterface { * } * ``` */ - loadBlocks: (params: ComposableFunctionArgs<{ identifiers: string[] }>) => Promise; + loadBlocks(params: ComposableFunctionArgs<{ identifiers: string[] }>): Promise; } diff --git a/packages/theme/composables/useCountrySearch/index.ts b/packages/theme/composables/useCountrySearch/index.ts index c21b75d1a..605559780 100644 --- a/packages/theme/composables/useCountrySearch/index.ts +++ b/packages/theme/composables/useCountrySearch/index.ts @@ -5,7 +5,7 @@ import { Maybe, Country } from '~/modules/GraphQL/types'; import { UseCountrySearchInterface } from './useCountrySearch'; /** - * The `useCountrySearch` composable is responsible for fetching a list of countries or a single country by id + * The `useCountrySearch` composable allows fetching a list of countries or a single country by ID * * See the {@link UseCountrySearchInterface} page for more information. */ diff --git a/packages/theme/composables/useCountrySearch/useCountrySearch.ts b/packages/theme/composables/useCountrySearch/useCountrySearch.ts index 19e7fb7ee..328364973 100644 --- a/packages/theme/composables/useCountrySearch/useCountrySearch.ts +++ b/packages/theme/composables/useCountrySearch/useCountrySearch.ts @@ -3,33 +3,58 @@ import { Countries, ComposableFunctionArgs } from '~/composables/types'; import { Maybe, Country } from '~/modules/GraphQL/types'; /** - * Errors returned by the {@link useCountrySearch} composable + * Errors that occured in the {@link useCountrySearch|useCountrySearch()} composable */ export interface UseCountrySearchErrors { - /** Error when searching for a country fails, otherwise is `null` */ + /** + * Contains error if `search` method failed, otherwise is `null` + */ search: Error | null - /** Error when loading the list of countries fails, otherwise is `null` */ + /** + * Contains error if `load` method failed, otherwise is `null` + */ load: Error | null } /** - * Params accepted by the `search` method in the {@link useCountrySearch} composable + * The params object accepted by the `save`, `update` and `remove` methods in the {@link useCountrySearch|useCountrySearch()} composable */ export type UseCountrySearchParams = ComposableFunctionArgs<{ id: string; }>; /** - * Represents data and methods returned from the {@link useCountrySearch} composable + * The refs and methods returned by the {@link useCountrySearch|useCountrySearch()} composable */ export interface UseCountrySearchInterface { - /** Fetches the array of registered countries */ - load (): Promise>; - /** Fetches a country by its id */ - search (params: UseCountrySearchParams): Promise>; - /** Returns the current state of search as computed boolean property */ + /** + * Fetches the array of registered countries + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#country} API endpoint + * and accepts the custom queries named `country`. + */ + load(): Promise>; + + /** + * Fetches a country by its id + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#countries} API endpoint + * and accepts the custom queries named `countries`. + */ + search(params: UseCountrySearchParams): Promise>; + + /** + * Indicates whether any of the methods is in progress + */ loading: DeepReadonly>; - /** Reactive object containing the error message, if search failed for any reason. */ + + /** + * Contains errors from the composable methods + */ error: DeepReadonly>; } diff --git a/packages/theme/composables/useCurrency/index.ts b/packages/theme/composables/useCurrency/index.ts index b7f06b5e7..a4129d226 100644 --- a/packages/theme/composables/useCurrency/index.ts +++ b/packages/theme/composables/useCurrency/index.ts @@ -13,7 +13,11 @@ import type { UseCurrencyChangeParams, } from './useCurrency'; -/** The `useCurrency()` composable allows loading and changing the currency. */ +/** + * The `useCurrency()` composable allows loading and changing the currency. + * + * See the {@link UseCurrencyInterface} for a list of methods and values available in this composable. + */ export function useCurrency(): UseCurrencyInterface { const { app } = useContext(); const loading = ref(false); diff --git a/packages/theme/composables/useCurrency/useCurrency.ts b/packages/theme/composables/useCurrency/useCurrency.ts index 2426f1be2..c968c911c 100644 --- a/packages/theme/composables/useCurrency/useCurrency.ts +++ b/packages/theme/composables/useCurrency/useCurrency.ts @@ -3,32 +3,52 @@ import type { ComposableFunctionArgs } from '~/composables/types'; import type { Currency } from '~/modules/GraphQL/types'; /** - * The {@link useCurrency} error object. The properties values' are the errors - * thrown by its methods. + * Errors that occured in the {@link useCurrency|useCurrency()} composable */ export interface UseCurrencyErrors { - /** Error when loading the currency fails, otherwise is `null`. */ + /** + * Contains error if `load` method failed, otherwise is `null` + */ load: Error | null; - /** Error when changing the currency fails, otherwise is `null`. */ + /** + * Contains error if `change` method failed, otherwise is `null` + */ change: Error | null; } -/** The params received by {@link useCurrency}'s `load` method. */ +/** + * The params object accepted by the `load` method in the {@link useCurrency|useCurrency()} composable + */ export type UseCurrencyLoadParams = ComposableFunctionArgs<{}>; -/** The params received by {@link useCurrency}'s `change` method. */ +/** + * The params object accepted by the `change` method in the {@link useCurrency|useCurrency()} composable + */ export type UseCurrencyChangeParams = { id: string }; -/** The interface provided by {@link useCurrency} composable. */ +/** + * The refs and methods returned by the {@link useCurrency|useCurrency()} composable + */ export interface UseCurrencyInterface { - /** Loads the currency and updates the configuration store. */ + /** + * Loads the currency and updates the configuration store + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#currency} API endpoint + * and accepts the custom queries named `currency`. + */ load(params?: UseCurrencyLoadParams): Promise; - /** Changes the currency and reloads the page. */ + /** + * Changes the currency and reloads the page + */ change(params: UseCurrencyChangeParams): void; - /** Contains errors from any of the composable methods. */ + /** + * Contains errors from the composable methods + */ error: DeepReadonly>; /** @@ -38,6 +58,8 @@ export interface UseCurrencyInterface { */ currency: ComputedRef; - /** Indicates whether any of the composable methods is in progress. */ + /** + * Indicates whether any of the methods is in progress + */ loading: Readonly>; } diff --git a/packages/theme/composables/useExternalCheckout/index.ts b/packages/theme/composables/useExternalCheckout/index.ts index 54c5dd549..ea54f6e6c 100644 --- a/packages/theme/composables/useExternalCheckout/index.ts +++ b/packages/theme/composables/useExternalCheckout/index.ts @@ -1,12 +1,11 @@ import { readonly, ref, useContext } from '@nuxtjs/composition-api'; import { Logger } from '~/helpers/logger'; -import { UseExternalCheckoutInterface } from '~/composables/useExternalCheckout/useExternalCheckout'; +import type { UseExternalCheckoutInterface } from '~/composables/useExternalCheckout/useExternalCheckout'; /** - * The `useExternalCheckout` composable is responsible for - * redirecting checkout process and depends on {@link https://github.com/Vendic/magento2-external-checkout | Magento 2 External Checkout for Vue Storefront} repository. + * The `useExternalCheckout` composable allows redirecting to external checkout process. It depends on the {@link https://github.com/Vendic/magento2-external-checkout | magento2-external-checkout repository}. * - * See the {@link UseExternalCheckoutInterface} page for more information. + * See the {@link UseExternalCheckoutInterface} for a list of methods and values available in this composable. */ export function useExternalCheckout(): UseExternalCheckoutInterface { const { app } = useContext(); diff --git a/packages/theme/composables/useExternalCheckout/useExternalCheckout.ts b/packages/theme/composables/useExternalCheckout/useExternalCheckout.ts index 54f8b8af5..9dfa9ae01 100644 --- a/packages/theme/composables/useExternalCheckout/useExternalCheckout.ts +++ b/packages/theme/composables/useExternalCheckout/useExternalCheckout.ts @@ -1,14 +1,27 @@ import { DeepReadonly, Ref } from '@nuxtjs/composition-api'; import { ComposableFunctionArgs } from '~/composables/types'; +/** + * The params object accepted by the `initializeCheckout` method in the {@link useExternalCheckout|useExternalCheckout()} composable + */ export type UseExternalCheckoutInitializeParams = ComposableFunctionArgs<{ baseUrl: string }>; -/** Represents the data and methods returned by the {@link useExternalCheckout} composable */ +/** + * The refs and methods returned by the {@link useExternalCheckout|useExternalCheckout()} composable + */ export interface UseExternalCheckoutInterface { - /** Initializes the checkout provider with the `baseUrl` */ + /** + * Initializes the checkout provider with the `baseUrl` + */ initializeCheckout(params: UseExternalCheckoutInitializeParams): string - /** Returns the loading state as a computed boolean */ + + /** + * Indicates whether any of the methods is in progress + */ loading: DeepReadonly>, - /** Returns errors when intializing the checkout */ + + /** + * Contains errors from the composable methods + */ error: DeepReadonly>, } diff --git a/packages/theme/composables/useImage/index.ts b/packages/theme/composables/useImage/index.ts index 36d2c8264..6117abcd0 100644 --- a/packages/theme/composables/useImage/index.ts +++ b/packages/theme/composables/useImage/index.ts @@ -3,9 +3,9 @@ import imageSizes from '~/enums/imageEnums'; import { UseImageInterface } from './useImage'; /** - * The `useImage` composable allows to extract an image path from magento URL + * The `useImage` composable allows extracting image paths from magento URL. * - * See {@link UseImageInterface} page for more details + * See the {@link UseImageInterface} for a list of methods and values available in this composable. * */ export function useImage(): UseImageInterface { // @ts-ignore diff --git a/packages/theme/composables/useImage/useImage.ts b/packages/theme/composables/useImage/useImage.ts index cb3285542..0d73099d1 100644 --- a/packages/theme/composables/useImage/useImage.ts +++ b/packages/theme/composables/useImage/useImage.ts @@ -23,10 +23,17 @@ export type ImageSizes = { }, }; -/** Represent data and methods returned by the {@link useImage} composable */ +/** + * The refs and methods returned by the {@link useImage|useImage()} composable + */ export interface UseImageInterface { - /** Extract image path from Magento URL. */ - getMagentoImage (fullImageUrl: string): string - /** Available image sizes */ + /** + * Extracts image path from Magento URL. + */ + getMagentoImage(fullImageUrl: string): string + + /** + * Available image sizes + */ imageSizes: ImageSizes } diff --git a/packages/theme/composables/useMagentoConfiguration/UseMagentoConfiguration.ts b/packages/theme/composables/useMagentoConfiguration/UseMagentoConfiguration.ts index 4f9316d1d..513b4d0be 100644 --- a/packages/theme/composables/useMagentoConfiguration/UseMagentoConfiguration.ts +++ b/packages/theme/composables/useMagentoConfiguration/UseMagentoConfiguration.ts @@ -1,17 +1,27 @@ import type { ComputedRef } from '@nuxtjs/composition-api'; import type { StoreConfig } from '~/../api-client/lib'; -/** The interface provided by {@link useMagentoConfiguration} composable. */ +/** + * The refs and methods returned by the {@link useMagentoConfiguration|useMagentoConfiguration()} composable + */ export interface UseMagentoConfigurationInterface { - /** The store configuration object. */ + /** + * Store configuration object. + */ storeConfig: ComputedRef; - /** The selected currency. */ + /** + * Currently active currency + */ selectedCurrency: ComputedRef; - /** The selected locale. */ + /** + * Currently active locale + */ selectedLocale: ComputedRef; - /** The selected store. */ + /** + * Currently active store + */ selectedStore: ComputedRef; } diff --git a/packages/theme/composables/useMagentoConfiguration/index.ts b/packages/theme/composables/useMagentoConfiguration/index.ts index c3863cd75..d8880ad9a 100644 --- a/packages/theme/composables/useMagentoConfiguration/index.ts +++ b/packages/theme/composables/useMagentoConfiguration/index.ts @@ -5,6 +5,8 @@ import type { UseMagentoConfigurationInterface } from './UseMagentoConfiguration /** * The `useMagentoConfiguration()` composable allows getting the Magento's major * definitions, e.g., the selected currency, store, locale, and config object. + * + * See the {@link UseMagentoConfigurationInterface} for a list of methods and values available in this composable. */ export function useMagentoConfiguration(): UseMagentoConfigurationInterface { const { diff --git a/packages/theme/composables/useNewsletter/index.ts b/packages/theme/composables/useNewsletter/index.ts index d292d6084..40d5ae9e1 100644 --- a/packages/theme/composables/useNewsletter/index.ts +++ b/packages/theme/composables/useNewsletter/index.ts @@ -11,6 +11,8 @@ import type { /** * The `useNewsletter()` composable allows updating the subscription status of * an email in the newsletter. + * + * See the {@link UseNewsletterInterface} for a list of methods and values available in this composable. */ export function useNewsletter(): UseNewsletterInterface { const context = useContext(); diff --git a/packages/theme/composables/useNewsletter/useNewsletter.ts b/packages/theme/composables/useNewsletter/useNewsletter.ts index 47b915123..eb227ed99 100644 --- a/packages/theme/composables/useNewsletter/useNewsletter.ts +++ b/packages/theme/composables/useNewsletter/useNewsletter.ts @@ -3,33 +3,38 @@ import type { ComposableFunctionArgs } from '~/composables/types'; import type { SubscriptionStatusesEnum } from '~/modules/GraphQL/types'; /** - * The {@link useNewsletter} error object. The properties values' are the errors - * thrown by its methods. + * Errors that occured in the {@link useNewsletter|useNewsletter()} composable */ export interface UseNewsletterErrors { - /** Error when updating subscription fails, otherwise is `null`. */ + /** + * Contains error if `updateSubscription` method failed, otherwise is `null` + */ updateSubscription: Error | null; } /** - * The params received by {@link useNewsletter}'s `updateSubscription` method. + * The params object accepted by the `updateSubscription` method in the {@link useNewsletter|useNewsletter()} composable */ export type UseNewsletterUpdateSubscriptionParams = ComposableFunctionArgs<{ email: string; }>; -/** The interface provided by {@link useNewsletter} composable. */ +/** + * The refs and methods returned by the {@link useNewsletter|useNewsletter()} composable + */ export interface UseNewsletterInterface { - /** Updates subscription status of an email in the newsletter. */ + /** + * Updates subscription status of an email in the newsletter + */ updateSubscription(params: UseNewsletterUpdateSubscriptionParams): Promise; /** - * Contains errors from any of the composable methods. - * - * Read {@link UseNewsletterErrors} documentation for more details. + * Contains errors from the composable methods */ error: DeepReadonly>; - /** Indicates whether any of the composable methods is in progress. */ + /** + * Indicates whether any of the methods is in progress + */ loading: Readonly>; } diff --git a/packages/theme/composables/useReview/index.ts b/packages/theme/composables/useReview/index.ts index db8bdd58f..1a06ada2d 100644 --- a/packages/theme/composables/useReview/index.ts +++ b/packages/theme/composables/useReview/index.ts @@ -15,7 +15,7 @@ import type { /** * The `useReview()` composable allows loading and adding product reviews * - * See the {@link UseReviewInterface} page for more information. + * See the {@link UseReviewInterface} for a list of methods and values available in this composable. */ export function useReview(): UseReviewInterface { const loading = ref(false); diff --git a/packages/theme/composables/useReview/useReview.ts b/packages/theme/composables/useReview/useReview.ts index b3392f1cb..7cb0eb3ad 100644 --- a/packages/theme/composables/useReview/useReview.ts +++ b/packages/theme/composables/useReview/useReview.ts @@ -1,7 +1,6 @@ import type { Ref, DeepReadonly } from '@nuxtjs/composition-api'; import type { ComposableFunctionArgs } from '~/composables/types'; import type { GetProductSearchParams } from '~/modules/catalog/product/types'; - import type { CreateProductReviewInput, ProductReviewQuery, @@ -11,46 +10,81 @@ import type { } from '~/modules/GraphQL/types'; /** - * Errors that occured in the `useReview` composable + * Errors that occured in the {@link useReview|useReview()} composable */ export interface UseReviewErrors { + /** + * Contains error if `search` method failed, otherwise is `null` + */ search: Error; + + /** + * Contains error if `addReview` method failed, otherwise is `null` + */ addReview: Error; + + /** + * Contains error if `loadReviewMetadata` method failed, otherwise is `null` + */ loadReviewMetadata: Error; + + /** + * Contains error if `loadCustomerReviews` method failed, otherwise is `null` + */ loadCustomerReviews: Error; } /** - * Parameters accepted by the `search` method in the `useReview` composable + * The params object accepted by the `search` method in the {@link useReview|useReview()} composable */ export type UseReviewSearchParams = ComposableFunctionArgs; /** - * Parameters accepted by the `addReview` method in the `useReview` composable + * The params object accepted by the `addReview` method in the {@link useReview|useReview()} composable */ export type UseReviewAddReviewParams = ComposableFunctionArgs; /** - * Represents the data returned from and functions available in the `useReview()` composable. + * The refs and methods returned by the {@link useCountrySearch|useCountrySearch()} composable */ export interface UseReviewInterface { /** * Fetches reviews for the product matching the provided filters + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#productReview} API endpoint + * and accepts the custom queries named `productReview`. */ search(params: UseReviewSearchParams): Promise; /** * Fetches product reviews created by the current customer + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#customerProductReview} API endpoint + * and accepts the custom queries named `reviews`. */ loadCustomerReviews(): Promise; /** * Fetches additional product reviews data + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#productReviewRatingsMetadata} API endpoint + * and accepts the custom queries named `productReviewRatingsMetadata`. */ loadReviewMetadata(): Promise; /** * Submits a new product review + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#createProductReview} API endpoint + * and accepts the custom queries named `createProductReview`. */ addReview(params: UseReviewAddReviewParams): Promise; diff --git a/packages/theme/composables/useStore/index.ts b/packages/theme/composables/useStore/index.ts index eee92ff79..978f4806e 100644 --- a/packages/theme/composables/useStore/index.ts +++ b/packages/theme/composables/useStore/index.ts @@ -13,7 +13,7 @@ import type { UseStoreInterface, UseStoreErrors } from '~/composables/useStore/u /** * The `useStore()` composable allows loading and changing currently active store * - * See the {@link UseStoreInterface} page for more information. + * See the {@link UseStoreInterface} for a list of methods and values available in this composable. */ export function useStore(): UseStoreInterface { const loading: Ref = ref(false); diff --git a/packages/theme/composables/useStore/useStore.ts b/packages/theme/composables/useStore/useStore.ts index f25049ce0..4e43ae503 100644 --- a/packages/theme/composables/useStore/useStore.ts +++ b/packages/theme/composables/useStore/useStore.ts @@ -3,15 +3,22 @@ import type { StoreConfig } from '~/modules/GraphQL/types'; import type { AvailableStores } from '~/composables/types'; /** - * Errors that occured in the `useStore` composable + * Errors that occured in the {@link useStore|useStore()} composable */ export interface UseStoreErrors { + /** + * Contains error if `load` method failed, otherwise is `null` + */ load: Error | null; + + /** + * Contains error if `change` method failed, otherwise is `null` + */ change: Error | null; } /** - * Represents the data returned from and functions available in the `useStore()` composable. + * The refs and methods returned by the {@link useStore|useStore()} composable */ export interface UseStoreInterface { /** @@ -21,6 +28,11 @@ export interface UseStoreInterface { /** * Fetches a list of available stores + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#availableStores} API endpoint + * and accepts the custom queries named `availableStores`. */ load(customQuery?: { availableStores: string }): Promise; @@ -35,7 +47,7 @@ export interface UseStoreInterface { loading: DeepReadonly>; /** - * Contains errors from any of the composable methods + * Contains errors from the composable methods */ error: DeepReadonly>; } diff --git a/packages/theme/composables/useUiHelpers/index.ts b/packages/theme/composables/useUiHelpers/index.ts index e618370d4..fa5130d7b 100644 --- a/packages/theme/composables/useUiHelpers/index.ts +++ b/packages/theme/composables/useUiHelpers/index.ts @@ -20,6 +20,8 @@ function reduceFilters(query: QueryParams) { /** * The `useUiHelpers()` composable allows handling the parameters for filtering, * searching, sorting and pagination in the URL search/query params. + * + * See the {@link UseUiHelpersInterface} for a list of methods and values available in this composable. */ export function useUiHelpers(): UseUiHelpersInterface { const route = useRoute(); diff --git a/packages/theme/composables/useUiNotification/index.ts b/packages/theme/composables/useUiNotification/index.ts index c16d7866b..3197d760d 100644 --- a/packages/theme/composables/useUiNotification/index.ts +++ b/packages/theme/composables/useUiNotification/index.ts @@ -17,7 +17,7 @@ const timeToLive = 3000; /** * The `useUiNotification()` composable allows showing notifications to the user. * - * See the {@link UseUiNotificationInterface} page for more information. + * See the {@link UseUiNotificationInterface} for a list of methods and values available in this composable. */ export function useUiNotification(): UseUiNotificationInterface { const { app } = useContext(); diff --git a/packages/theme/composables/useUiState/index.ts b/packages/theme/composables/useUiState/index.ts index 27f06019d..a69809bf9 100644 --- a/packages/theme/composables/useUiState/index.ts +++ b/packages/theme/composables/useUiState/index.ts @@ -15,7 +15,7 @@ const state = reactive({ /** * The `useUiState()` composable is a global store for managing UI state * - * See the {@link UseUiStateInterface} page for more information. + * See the {@link UseUiStateInterface} for a list of methods and values available in this composable. */ export function useUiState(): UseUiStateInterface { const toggleMobileMenu = () => { diff --git a/packages/theme/composables/useUrlResolver/UseUrlResolver.ts b/packages/theme/composables/useUrlResolver/UseUrlResolver.ts index 524010c3e..bc91c8a2b 100644 --- a/packages/theme/composables/useUrlResolver/UseUrlResolver.ts +++ b/packages/theme/composables/useUrlResolver/UseUrlResolver.ts @@ -2,32 +2,36 @@ import type { DeepReadonly, Ref } from '@nuxtjs/composition-api'; import type { EntityUrl } from '~/modules/GraphQL/types'; /** - * The {@link useUrlResolver} error object. The properties values' are the - * errors thrown by its methods. + * Errors that occured in the {@link UseUrlResolverErrors|UseUrlResolverErrors()} composable */ export interface UseUrlResolverErrors { /** - * Error when searching the resolver for current route URL fails, otherwise is - * `null`. + * Contains error if `search` method failed, otherwise is `null` */ search: Error | null; } -/** The interface provided by {@link useUrlResolver} composable. */ +/** + * The refs and methods returned by the {@link useUrlResolver|useUrlResolver()} composable + */ export interface UseUrlResolverInterface { - /** The current route path. */ + /** + * The current route path + */ path: string; /** - * Contains errors from any of the composable methods. - * - * @see {@link UseUrlResolverErrors} documentation for more details. + * Contains errors from the composable methods */ error: DeepReadonly>; - /** Indicates whether any of the composable methods is in progress. */ + /** + * Indicates whether any of the methods is in progress + */ loading: Readonly>; - /** Searches the resolver for current route URL. */ + /** + * Searches the resolver for current route URL + */ search(): Promise; } diff --git a/packages/theme/composables/useUrlResolver/index.ts b/packages/theme/composables/useUrlResolver/index.ts index 3f3c8d1c7..f93ecdf0f 100644 --- a/packages/theme/composables/useUrlResolver/index.ts +++ b/packages/theme/composables/useUrlResolver/index.ts @@ -11,6 +11,8 @@ import type { UseUrlResolverErrors, UseUrlResolverInterface } from './UseUrlReso /** * The `useUrlResolver()` composable allows searching the resolver for current * route path (URL). + * + * See the {@link UseUrlResolverInterface} for a list of methods and values available in this composable. */ export function useUrlResolver(): UseUrlResolverInterface { const route = useRoute(); diff --git a/packages/theme/modules/catalog/category/composables/useCategorySearch/index.ts b/packages/theme/modules/catalog/category/composables/useCategorySearch/index.ts index e74aad84d..88c495211 100644 --- a/packages/theme/modules/catalog/category/composables/useCategorySearch/index.ts +++ b/packages/theme/modules/catalog/category/composables/useCategorySearch/index.ts @@ -4,8 +4,10 @@ import type { CategorySearchQueryVariables, CategoryTree } from '~/modules/Graph import type { UseCategorySearchErrors, UseCategorySearchInterface } from './useCategorySearch'; /** - * The `useCategorySearch()` composable allows searching for categories. It is + * The `useCategorySearch` composable allows searching for categories. It is * commonly used in subtrees navigation. + * + * See the {@link UseCategorySearchInterface} for a list of methods and values available in this composable. */ export function useCategorySearch(): UseCategorySearchInterface { const { app } = useContext(); diff --git a/packages/theme/modules/catalog/category/composables/useCategorySearch/useCategorySearch.ts b/packages/theme/modules/catalog/category/composables/useCategorySearch/useCategorySearch.ts index 083a8177e..3839e2bd2 100644 --- a/packages/theme/modules/catalog/category/composables/useCategorySearch/useCategorySearch.ts +++ b/packages/theme/modules/catalog/category/composables/useCategorySearch/useCategorySearch.ts @@ -3,18 +3,23 @@ import type { CategorySearchQueryVariables, CategoryTree } from '~/modules/Graph import type { ComposableFunctionArgs } from '~/composables/types'; /** - * The {@link useCategorySearch} error object. The properties values' are the - * errors thrown by its methods. + * Errors that occured in the {@link useCategorySearch|useCategorySearch()} composable */ export interface UseCategorySearchErrors { - /** Error when searching for categories fails, otherwise is `null`. */ + /** + * Contains error if `search` method failed, otherwise is `null` + */ search: Error | null; } -/** The params received by {@link useCategorySearch}'s `search` method. */ +/** + * The params object accepted by the `search` method in the {@link useCategorySearch|useCategorySearch()} composable + */ export type UseCategorySearchParams = ComposableFunctionArgs; -/** The interface provided by {@link useCategorySearch} composable. */ +/** + * The refs and methods returned by the {@link useCategorySearch|useCategorySearch()} composable + */ export interface UseCategorySearchInterface { /** * Searches for categories using the received filters and updates the @@ -22,7 +27,9 @@ export interface UseCategorySearchInterface { */ search(searchParams: UseCategorySearchParams): Promise; - /** Contains errors from any of the composable methods. */ + /** + * Contains errors from the composable methods + */ error: DeepReadonly>; /** @@ -31,6 +38,8 @@ export interface UseCategorySearchInterface { */ result: DeepReadonly>; - /** Indicates whether any of the composable methods is in progress. */ + /** + * Indicates whether any of the methods is in progress + */ loading: Readonly>; } diff --git a/packages/theme/modules/checkout/composables/useBilling/index.ts b/packages/theme/modules/checkout/composables/useBilling/index.ts index 4283805e4..872f8cd6d 100644 --- a/packages/theme/modules/checkout/composables/useBilling/index.ts +++ b/packages/theme/modules/checkout/composables/useBilling/index.ts @@ -12,8 +12,10 @@ import type { } from './useBilling'; /** - * The `useBilling()` composable allows loading and saving billing information + * The `useBilling` composable allows loading and saving billing information * of the current cart. + * + * See the {@link UseBillingInterface} for a list of methods and values available in this composable. */ export function useBilling(): UseBillingInterface { const context = useContext(); diff --git a/packages/theme/modules/checkout/composables/useBilling/useBilling.ts b/packages/theme/modules/checkout/composables/useBilling/useBilling.ts index d3d607052..cfdf2fae1 100644 --- a/packages/theme/modules/checkout/composables/useBilling/useBilling.ts +++ b/packages/theme/modules/checkout/composables/useBilling/useBilling.ts @@ -2,7 +2,9 @@ import type { Ref } from '@nuxtjs/composition-api'; import type { BillingCartAddress } from '~/modules/GraphQL/types'; import { ComposableFunctionArgs } from '~/composables/types'; -/** The object used by {@link useBilling} to save new billing information. */ +/** + * The object used by the {@link useBilling|useBilling()} composable to save new billing information + */ export interface BillingDetails { apartment?: string; city?: string; @@ -20,26 +22,35 @@ export interface BillingDetails { } /** - * The {@link useBilling} error object. The properties values' are the errors - * thrown by its methods. + * Errors that occured in the {@link useBilling|useBilling()} composable */ export interface UseBillingError { - /** Error when loading the billing information fails, otherwise is `null`. */ + /** + * Contains error if `load` method failed, otherwise is `null` + */ load: Error | null; - /** Error when saving the billing information fails, otherwise is `null`. */ + /** + * Contains error if `save` method failed, otherwise is `null` + */ save: Error | null; } -/** The params received by {@link useBilling}'s `load` method. */ +/** + * The params object accepted by the `load` method in the {@link useBilling|useBilling()} composable + */ export type UseBillingLoadParams = ComposableFunctionArgs<{}>; -/** The params received by {@link useBilling}'s `save` method. */ +/** + * The params object accepted by the `save` method in the {@link useBilling|useBilling()} composable + */ export interface UseBillingSaveParams { billingDetails: BillingDetails; } -/** The interface provided by {@link useBilling} composable. */ +/** + * The refs and methods returned by the {@link useBilling|useBilling()} composable + */ export interface UseBillingInterface { /** * Loads the billing information. It returns a `Promise` that resolves into @@ -53,9 +64,13 @@ export interface UseBillingInterface { */ save(params: UseBillingSaveParams): Promise; - /** Contains errors from any of the composable methods. */ + /** + * Contains errors from the composable methods + */ error: Readonly>; - /** Indicates whether any of the methods is in progress. */ + /** + * Indicates whether any of the methods is in progress + */ loading: Readonly>; } diff --git a/packages/theme/modules/checkout/composables/useShippingProvider/index.ts b/packages/theme/modules/checkout/composables/useShippingProvider/index.ts index ccd43afe6..a455fbe5c 100644 --- a/packages/theme/modules/checkout/composables/useShippingProvider/index.ts +++ b/packages/theme/modules/checkout/composables/useShippingProvider/index.ts @@ -11,9 +11,11 @@ import type { } from './useShippingProvider'; /** - * The `useShippingProvider()` composable allows loading the shipping provider + * The `useShippingProvider` composable allows loading the shipping provider * for the current cart and saving (selecting) other shipping provider for the * same cart. + * + * See the {@link UseShippingProviderInterface} for a list of methods and values available in this composable. */ export function useShippingProvider(): UseShippingProviderInterface { const loading = ref(false); diff --git a/packages/theme/modules/checkout/composables/useShippingProvider/useShippingProvider.ts b/packages/theme/modules/checkout/composables/useShippingProvider/useShippingProvider.ts index e7d3642c2..7c9e53b0e 100644 --- a/packages/theme/modules/checkout/composables/useShippingProvider/useShippingProvider.ts +++ b/packages/theme/modules/checkout/composables/useShippingProvider/useShippingProvider.ts @@ -3,41 +3,59 @@ import type { SelectedShippingMethod } from '~/modules/GraphQL/types'; import type { ComposableFunctionArgs } from '~/composables/types'; /** - * The {@link useShippingProvider} error object. The properties values' are the - * errors thrown by its methods. + * Errors that occured in the {@link useShippingProvider|useShippingProvider()} composable */ export interface UseShippingProviderErrors { - /** Error when loading the shipping provider fails, otherwise is `null`. */ + /** + * Contains error if `load` method failed, otherwise is `null` + */ load: Error | null; - /** Error when saving new shipping provider fails, otherwise is `null`. */ + /** + * Contains error if `save` method failed, otherwise is `null` + */ save: Error | null; } -/** The params received by {@link useShippingProvider}'s `load` method. */ +/** + * The params object accepted by the `load` method in the {@link useShippingProvider|useShippingProvider()} composable + */ export type UseShippingProviderLoadParams = ComposableFunctionArgs<{}>; -/** The params received by {@link useShippingProvider}'s `save` method. */ +/** + * The params object accepted by the `save` method in the {@link useShippingProvider|useShippingProvider()} composable + */ export type UseShippingProviderSaveParams = ComposableFunctionArgs<{ // TODO: Define this type. shippingMethod: any; }>; -/** The interface provided by {@link useShippingProvider} composable. */ +/** + * The refs and methods returned by the {@link useShippingProvider|useShippingProvider()} composable + */ export interface UseShippingProviderInterface { /** - * Contains errors from any of the composable methods. - * - * @see {@link UseShippingProviderErrors} documentation for more details. + * Contains errors from the composable methods */ error: Readonly>; - /** Indicates whether any of the composable methods is in progress. */ + /** + * Indicates whether any of the methods is in progress + */ loading: Readonly>; - /** Loads the shipping provider for current cart. */ + /** + * Loads the shipping provider for current cart + */ load(params?: UseShippingProviderLoadParams): Promise; - /** Save new shipping provider for current cart. */ + /** + * Save new shipping provider for current cart + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#setShippingMethodsOnCart} API endpoint + * and accepts the custom queries named `setShippingMethodsOnCart`. + */ save(params: UseShippingProviderSaveParams): Promise; } diff --git a/packages/theme/modules/customer/composables/useAddresses/useAddresses.ts b/packages/theme/modules/customer/composables/useAddresses/useAddresses.ts index f7e430d09..3b017ff11 100644 --- a/packages/theme/modules/customer/composables/useAddresses/useAddresses.ts +++ b/packages/theme/modules/customer/composables/useAddresses/useAddresses.ts @@ -4,52 +4,38 @@ import type { CustomerAddress } from '~/modules/GraphQL/types'; /** * Errors that occured in the {@link useAddresses|useAddresses()} composable - * - * @example - * - * Check if removing a customer address failed: - * - * ```typescript - * import { useAddresses } from '~/modules/customer/composables/useAddresses'; - * - * export default { - * setup(props) { - * const { error, remove } = useAddresses(); - * - * const onRemove = async (address: CustomerAddress) => { - * await remove(address); - * - * if (error.value.remove) { - * // handle removing error - * } - * }; - * - * return { onRemove }; - * } - * } - * ``` */ export interface UseAddressesErrors { - /** Error when loading customer addresses fails, otherwise is `null`. */ + /** + * Contains error if `load` method failed, otherwise is `null` + */ load: Error | null; - /** Error when saving a new customer address fails, otherwise is `null`. */ + /** + * Contains error if `save` method failed, otherwise is `null` + */ save: Error | null; - /** Error when removing a customer address fails, otherwise is `null`. */ + /** + * Contains error if `remove` method failed, otherwise is `null` + */ remove: Error | null; - /** Error when updating a customer address fails, otherwise is `null`. */ + /** + * Contains error if `update` method failed, otherwise is `null` + */ update: Error | null; } -/** The params object required to **save**, **update** or **remove** a customer address. */ +/** + * The params object accepted by the `save`, `update` and `remove` methods in the {@link useAddresses|useAddresses()} composable + */ export interface UseAddressesParamsInput { address: CustomerAddress; } /** - * The refs and methods returned by the {@link useAddresses|useAddresses()} composable. + * The refs and methods returned by the {@link useAddresses|useAddresses()} composable */ export interface UseAddressesInterface { /** diff --git a/packages/theme/modules/customer/composables/useUserAddress/index.ts b/packages/theme/modules/customer/composables/useUserAddress/index.ts index f700c9533..512a461f4 100644 --- a/packages/theme/modules/customer/composables/useUserAddress/index.ts +++ b/packages/theme/modules/customer/composables/useUserAddress/index.ts @@ -19,7 +19,7 @@ import type { /** * The `useUserAddress()` composable allows loading and manipulating addresses of the current user. * - * See the {@link UseUserAddressInterface} page for more information. + * See the {@link UseUserAddressInterface} for a list of methods and values available in this composable. */ export function useUserAddress(): UseUserAddressInterface { const loading = ref(false); diff --git a/packages/theme/modules/customer/composables/useUserAddress/useUserAddress.ts b/packages/theme/modules/customer/composables/useUserAddress/useUserAddress.ts index 489e3d817..4e5770fe3 100644 --- a/packages/theme/modules/customer/composables/useUserAddress/useUserAddress.ts +++ b/packages/theme/modules/customer/composables/useUserAddress/useUserAddress.ts @@ -4,53 +4,87 @@ import type { ComposableFunctionArgs } from '~/composables/types'; import { Customer } from '~/modules/GraphQL/types'; /** - * Errors that occured in the `useUserAddress` composable + * Errors that occured in the {@link UseUserAddressErrors|UseUserAddressErrors()} composable */ export interface UseUserAddressErrors { + /** + * Contains error if `addAddress` method failed, otherwise is `null` + */ addAddress: Error | null; + + /** + * Contains error if `deleteAddress` method failed, otherwise is `null` + */ deleteAddress: Error | null; + + /** + * Contains error if `updateAddress` method failed, otherwise is `null` + */ updateAddress: Error | null; + + /** + * Contains error if `load` method failed, otherwise is `null` + */ load: Error | null; + + /** + * Contains error if `setDefaultAddress` method failed, otherwise is `null` + */ setDefaultAddress: Error | null; } /** - * Parameters accepted by the `addAddress` method in the `useUserAddress` composable + * The params object accepted by the `addAddress` method in the {@link useUserAddress|useUserAddress()} composable */ export type UseUserAddressAddAddressParams = ComposableFunctionArgs<{ address: CustomerAddress; }>; /** - * Parameters accepted by the `updateAddress` method in the `useUserAddress` composable + * The params object accepted by the `updateAddress` method in the {@link useUserAddress|useUserAddress()} composable */ export type UseUserAddressUpdateAddressParams = ComposableFunctionArgs<{ address: CustomerAddress; }>; /** - * Parameters accepted by the `setDefaultAddress` method in the `useUserAddress` composable + * The params object accepted by the `setDefaultAddress` method in the {@link useUserAddress|useUserAddress()} composable */ export type UseUserAddressSetDefaultAddressParams = ComposableFunctionArgs<{ address: CustomerAddress; }>; /** - * Represents the data returned from and functions available in the `useUserAddress()` composable. + * The refs and methods returned by the {@link useUserAddress|useUserAddress()} composable */ export interface UseUserAddressInterface { /** * Adds address to the profile of the current user + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#createCustomerAddress} API endpoint + * and accepts the custom queries named `createCustomerAddress`. */ addAddress(params: UseUserAddressAddAddressParams): Promise; /** * Deletes address from the profile of the current user + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#deleteCustomerAddress} API endpoint + * and accepts the custom queries named `deleteCustomerAddress`. */ deleteAddress(address: CustomerAddress): Promise; // TODO: Should accept custom queries /** * Updates an existing address from the profile of the current user + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#updateCustomerAddress} API endpoint + * and accepts the custom queries named `updateCustomerAddress`. */ updateAddress(params: UseUserAddressUpdateAddressParams): Promise; @@ -61,6 +95,11 @@ export interface UseUserAddressInterface { /** * Sets an existing address as the default for the current user + * + * @remarks + * + * Internally, it calls the {@link @vue-storefront/magento-api#updateCustomerAddress} API endpoint + * and accepts the custom queries named `updateCustomerAddress`. */ setDefaultAddress(params: UseUserAddressSetDefaultAddressParams): Promise;