docs: #30 add docs about composables

docs/composables/use-category.md

@@ -4,61 +4,31 @@
 
 `useCategory` composable is responsible for fetching a list of categories. A common usage scenario for this composable is navigation.
 
+::: warning
+This composable uses a custom useCategoryFactory that is not part of the Vue Storefront Core package. Functionality and types can differ from other integrations. For more details visit [code repository](https://github.com/vuestorefront/vendure/blob/main/packages/composables/src/factories/useCategoryFactory.ts)
+:::
+
 ## API
 
 - `search` - a main querying function that is used to query categories from eCommerce platform and populate the `categories` object with the result. Every time you invoke this function API request is made. This method accepts a single `params` object. The `params` has the following options:
 
-    - `searchParams`
-
-      - `id: string`
-      - `slug: string`
-
-    - `customQuery?: CustomQuery` 
-
+  - `params: CollectionParams & { customQuery?: CustomQuery }`
+
 ```ts
+type CollectionParams = {
+  options?: CollectionListOptions;
+}
+
 type CustomQuery = {
   categories: string
 }
 ```
 
-- `categories: Category[]` - a main data object that contains an array of categories fetched by `search` method.
+<https://www.vendure.io/docs/graphql-api/shop/input-types/#collectionlistoptions>
 
-```ts
-type Category = {
-  __typename?: "Category";
-  id: Scalars["String"];
-  key?: Maybe<Scalars["String"]>;
-  version: Scalars["Long"];
-  name?: Maybe<Scalars["String"]>;
-  nameAllLocales: Array<LocalizedString>;
-  description?: Maybe<Scalars["String"]>;
-  descriptionAllLocales?: Maybe<Array<LocalizedString>>;
-  slug?: Maybe<Scalars["String"]>;
-  slugAllLocales: Array<LocalizedString>;
-  ancestorsRef: Array<Reference>;
-  ancestors: Array<Category>;
-  parentRef?: Maybe<Reference>;
-  parent?: Maybe<Category>;
-  orderHint: Scalars["String"];
-  externalId?: Maybe<Scalars["String"]>;
-  metaTitle?: Maybe<Scalars["String"]>;
-  metaKeywords?: Maybe<Scalars["String"]>;
-  metaDescription?: Maybe<Scalars["String"]>;
-  productCount: Scalars["Int"];
-  stagedProductCount: Scalars["Int"];
-  childCount: Scalars["Int"];
-  children?: Maybe<Array<Category>>;
-  createdAt: Scalars["DateTime"];
-  lastModifiedAt: Scalars["DateTime"];
-  assets: Array<Asset>;
-  customFieldsRaw?: Maybe<Array<RawCustomField>>;
-  customFields?: Maybe<Type>;
-  custom?: Maybe<CustomFieldsType>;
-  createdBy?: Maybe<Initiator>;
-  lastModifiedBy?: Maybe<Initiator>;
-  customFieldList?: Maybe<Array<CustomField>>;
-}
-```
+- `categories: CollectionList` - a main data object that contains an array of category items fetched by `search` method.
+
+<https://www.vendure.io/docs/graphql-api/shop/object-types/#collectionlist>
 
 - `loading: boolean` - a reactive object containing information about loading state of your `search` method.
 
@@ -73,13 +43,16 @@ interface UseCategoryErrors {
 ## Getters
 
 - `getNavigation` - returns global category navigation.
+
 - `getTotalItems` - returns total number of categories.
 
+- `getTree` - returns category tree (not used in favor of `facetGetters.getTree`)
 
 ```ts
 interface ExtendedCategoryGetters extends CategoryGetters<Collection> {
   getNavigation: (collectionList: CollectionList) => AgnosticCategoryNavigation[];
   getTotalItems: (collectionList: CollectionList) => number;
+  getTree: (category: Collection) => AgnosticCategoryTree
 }
 
 type AgnosticCategoryNavigation = {

docs/composables/use-facet.md

@@ -7,36 +7,23 @@
 * products,
 * categories,
 * breadcrumbs.
-
-What makes it powerful is the ability to accept multiple filters, allowing to narrow down the results to a specific category, search term, etc.
-
-For more information about faceting, please refer to [this page](../composables/use-facet.md).
+* facets
 
 ## API
 
 `useFacet` contains the following properties:
 
-- `search` - function for searching and classifying records, allowing users to browse the catalog data. It accepts a single object as a parameter with following signature:
+* `search` - function for searching and classifying records, allowing users to browse the catalog data. It accepts a single object as a parameter with following signature:
 
-```ts
-interface AgnosticFacetSearchParams {
-  categorySlug?: string;
-  rootCatSlug?: string;
-  term?: string;
-  page?: number;
-  itemsPerPage?: number;
-  sort?: string;
-  filters?: Record<string, string[]>;
-  metadata?: any;
-  [x: string]: any;
-}
-```
+<https://www.vendure.io/docs/graphql-api/shop/input-types/#searchinput>
+
+* `result` - reactive data object containing the response from the backend.
 
-- `result` - reactive data object containing the response from the backend.
+<https://www.vendure.io/docs/graphql-api/shop/object-types/#searchresponse>
 
-- `loading` - reactive object containing information about the loading state of `search`.
+* `loading` - reactive object containing information about the loading state of `search`.
 
-- `error` - reactive object containing the error message, if `search` failed for any reason.
+* `error` - reactive object containing the error message, if `search` failed for any reason.
 
 ```ts
 interface UseFacetErrors {
@@ -45,32 +32,39 @@ interface UseFacetErrors {
 ```
 
 ## Getters
-Because the `result` property is a raw response with some additional properties, it's recommended to use `facetGetters` for accessing any data from it. It includes the following helper functions:
 
-- `getAll` - returns all available facets.
+* `getGrouped` - returns grouped facets by facet name.
 
-- `getGrouped` - returns grouped facets by facet name.
+* `getSortOptions` - returns available and currently selected sorting options.
 
-- `getCategoryTree` - return the tree of nested categories.
+* `getProducts` - returns products matching current filters.
 
-- `getSortOptions` - returns available and currently selected sorting options.
+* `getPagination` - returns pagination information.
 
-- `getProducts` - returns products matching current filters.
+* `getTree` - returns current category tree.
 
-- `getPagination` - returns pagination information.
+* `getBreadcrumbsFromSlug` - returns breadcrumbs from current slug.
 
-- `getBreadcrumbs` - returns breadcrumbs information.
+* `getAgnosticSearchResult` - returns agnostic search result.
 
+* `getCategoryTree` - return the tree of nested categories (not used in favor of `getTree`).
+
+* `getBreadcrumbs` - returns breadcrumbs information (not used in favor of `getBreadcrumbsFromSlug`).
+
+* `getAll` - TBA.
 
 ```ts
 interface FacetsGetters {
-  getAll: (searchData: SearchData, criteria?: string[]) => AgnosticFacet[];
-  getGrouped: (searchData: SearchData, criteria?: string[]) => AgnosticGroupedFacet[];
-  getCategoryTree: (searchData: SearchData) => AgnosticCategoryTree;
-  getSortOptions: (searchData: SearchData) => AgnosticSort;
-  getProducts: (searchData: SearchData) => ProductVariant[];
-  getPagination: (searchData: SearchData) => AgnosticPagination;
-  getBreadcrumbs: (searchData: SearchData) => AgnosticBreadcrumb[];
+  getAll: (searchData: FacetSearchResult<AgnosticSearchResult>, criteria?: string[]) => AgnosticFacet[];
+  getGrouped: (searchData: FacetSearchResult<AgnosticSearchResult>, criteria?: string[]) => AgnosticGroupedFacet[];
+  getCategoryTree: (searchData: FacetSearchResult<AgnosticSearchResult>) => AgnosticCategoryTree;
+  getSortOptions: (searchData: FacetSearchResult<AgnosticSearchResult>) => AgnosticSort;
+  getProducts: (searchData: FacetSearchResult<AgnosticSearchResult>) => ProductVariant[];
+  getPagination: (searchData: FacetSearchResult<AgnosticSearchResult>) => AgnosticPagination;
+  getBreadcrumbs: (searchData: FacetSearchResult<AgnosticSearchResult>) => AgnosticBreadcrumb[];
+  getTree: (category: Collection) => AgnosticCategoryTree | null;
+  getBreadcrumbsFromSlug: (searchResult: FacetSearchResult<AgnosticSearchResult>, slug: string) => AgnosticBreadcrumb[]
+  getAgnosticSearchResult: (searchResultValue: SearchResultValue<SearchResponse, SearchInput>) => FacetSearchResult<AgnosticSearchResult>;
 }
 
 interface AgnosticFacet {
@@ -104,7 +98,6 @@ interface AgnosticSort {
   selected: string;
 }
 
-type SearchData = FacetSearchResult<FacetResultsData>
 
 interface FacetSearchResult {
   data;
@@ -136,31 +129,23 @@ interface AgnosticBreadcrumb {
   link: string;
 }
 
-interface FacetResultsData {
-  products: ProductVariant[];
-  categories: Category[];
-  facets: Record<string, Filter>;
+type AgnosticSearchResult = {
+  products: SearchResult[];
+  categories: CollectionResult[];
+  facets: FacetValueResult[];
   total: number;
   perPageOptions: number[];
   itemsPerPage: number;
 }
 
-type ProductVariant = {
-  __typename?: "ProductVariant";
-  id: Scalars["Int"];
-  key?: Maybe<Scalars["String"]>;
-  sku?: Maybe<Scalars["String"]>;
-  prices?: Maybe<Array<ProductPrice>>;
-  price?: Maybe<ProductPrice>;
-  images: Array<Image>;
-  assets: Array<Asset>;
-  availability?: Maybe<ProductVariantAvailabilityWithChannels>;
-  attributesRaw: Array<RawProductAttribute>;
-  attributes: ProductType;
-  attributeList: Array<Attribute>;
+type SearchResultValue<SEARCH_DATA, SEARCH_INPUT> = {
+  data?: SEARCH_DATA;
+  input?: SEARCH_INPUT;
 }
 ```
 
+<https://www.vendure.io/docs/graphql-api/shop/object-types/#searchresponse>
+
 ## Example
 
 ```js
@@ -171,20 +156,24 @@ setup(props, context) {
 
   onSSR(async () => {
     await search({
-      categorySlug: 'clothing',
-      sort: 'latest',
-      itemsPerPage: 10,
-      term: 'some search query'
+      collectionSlug: 'clothing',
+      sort: { price: 'ASC'},
+      take: 10,
+      groupByProduct: true, // To return only master variant
     });
   });
 
+    // Will be refactored to data mapper in theme folder
+    const searchResult = computed(() => facetGetters.getAgnosticSearchResult(result.value)); // Convert raw result to agnostic search result 
+
+    const sortBy = computed(() => facetGetters.getSortOptions(searchResult.value));
+    const facets = computed(() => facetGetters.getGrouped(searchResult.value));
+    const products = computed(() => facetGetters.getProducts(searchResult.value));
+
   return {
-    products: computed(() => facetGetters.getProducts(result.value)),
-    categoryTree: computed(() => facetGetters.getCategoryTree(result.value)),
-    breadcrumbs: computed(() => facetGetters.getBreadcrumbs(result.value)),
-    sortBy: computed(() => facetGetters.getSortOptions(result.value)),
-    facets: computed(() => facetGetters.getGrouped(result.value, ['color', 'size'])),
-    pagination: computed(() => facetGetters.getPagination(result.value)),
+    sortBy,
+    facets,
+    products,
     loading
   }
 }