docs: update composables docs

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]'],
         ],
       },
       {

packages/theme/composables/useApi/index.ts

@@ -1,20 +1,58 @@
 import { useContext } from '@nuxtjs/composition-api';
 import type { Variables } from 'graphql-request';
 
-type Request = <DATA = any, VARIABLES extends Variables = Variables>(
+export type Request = <DATA = any, VARIABLES extends Variables = Variables>(
   document: string,
   variables?: VARIABLES,
   requestHeaders?: HeadersInit
 ) => Promise<DATA>;
 
-/** 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<number | null>(null);
- *     const loading = ref(false);
- *     const error = ref<Error | null>(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();

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();

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<StoreConfig>,
-  /** Return state of loadConfig Function as computed property */
+
+  /**
+   * Indicates whether any of the methods is in progress
+   */
   loading: DeepReadonly<Ref<boolean>>,
-  /** Function to load the config */
-  load (): Promise<void>
+
+  /**
+   * Loads store configuration
+   */
+  load(): Promise<void>
 }

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<boolean> = ref(false);