Skip to content

Commit

Permalink
docs(composables): added documentation for composables (vuestorefront…
Browse files Browse the repository at this point in the history
…#1413)

* docs(composables): added useAddresses, useApi, useBilling, useCart, useCategory docs
* docs: added useCategorySearch composable doc
* docs: added useConfig
  • Loading branch information
skirianov authored Feb 3, 2023
1 parent 0352188 commit db2f054
Show file tree
Hide file tree
Showing 7 changed files with 814 additions and 0 deletions.
214 changes: 214 additions & 0 deletions docs/composition/useAddresses.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,214 @@
# useAddresses composable

`useAddresses` composable allows loading and manipulating addresses of the current user. These addresses can be used for both billing and shipping.

This composable can be found in the `modules` folder.

## API
`useAddresses` composable returns the following properties:

- `load` - function that loads addresses of the current customer
- `save` - function that saves a new address in the profile of the current customer
- `update` - function that updates an existing address in the profile of the current customer
- `remove` - function that removes an existing address from the profile of the current customer
- `error` - ref that contains an errors from the composable methods
- `loading` - ref that contains information whether any of the composable methods is loading

## Interfaces

```ts
/**
* Almost every method is extending this type
*/
type ComposableFunctionArgs<T> = T & {
customQuery?: CustomQuery;
customHeaders?: CustomHeaders;
};

interface CustomerAddress {
/** The city or town */
city?: Maybe<Scalars['String']>;
/** The customer's company */
company?: Maybe<Scalars['String']>;
/** The customer's country */
country_code?: Maybe<CountryCodeEnum>;
/**
The customer's country
@deprecated Use `country_code` instead.
*/
country_id?: Maybe<Scalars['String']>;
/** @deprecated Custom attributes should not be put into container */
custom_attributes?: Maybe<Array<Maybe<CustomerAddressAttribute>>>;
/**
The customer ID
@deprecated customer_id is not needed as part of CustomerAddress, address ID (id) is unique identifier for the addresses.
*/
customer_id?: Maybe<Scalars['Int']>;
/** Indicates whether the address is the default billing address */
default_billing?: Maybe<Scalars['Boolean']>;
/** Indicates whether the address is the default shipping address */
default_shipping?: Maybe<Scalars['Boolean']>;
/** Address extension attributes */
extension_attributes?: Maybe<Array<Maybe<CustomerAddressAttribute>>>;
/** The fax number */
fax?: Maybe<Scalars['String']>;
/** The first name of the person associated with the shipping/billing address */
firstname?: Maybe<Scalars['String']>;
/** The ID assigned to the address object */
id?: Maybe<Scalars['Int']>;
/** The family name of the person associated with the shipping/billing address */
lastname?: Maybe<Scalars['String']>;
/** The middle name of the person associated with the shipping/billing address */
middlename?: Maybe<Scalars['String']>;
/** The customer's ZIP or postal code */
postcode?: Maybe<Scalars['String']>;
/** An honorific, such as Dr., Mr., or Mrs. */
prefix?: Maybe<Scalars['String']>;
/** An object containing the region name, region code, and region ID */
region?: Maybe<CustomerAddressRegion>;
/** The unique ID for a pre-defined region */
region_id?: Maybe<Scalars['Int']>;
/** An array of strings that define the street number and name */
street?: Maybe<Array<Maybe<Scalars['String']>>>;
/** A value such as Sr., Jr., or III */
suffix?: Maybe<Scalars['String']>;
/** The telephone number */
telephone?: Maybe<Scalars['String']>;
/** The customer's Value-added tax (VAT) number (for corporate customers) */
vat_id?: Maybe<Scalars['String']>;
}

interface UseAddressesParamsInput {
address: CustomerAddress;
}

interface UseAddressesInterface {
error: Ref<UseAddressesErrors>;
loading: Ref<boolean>;
load(customQuery?: CustomQuery, customHeaders?: CustomHeaders): Promise<CustomerAddress[]>;
save(params: ComposableFunctionArgs<UseAddressesParamsInput>): Promise<CustomerAddress>;
update(params: ComposableFunctionArgs<UseAddressesParamsInput>): Promise<CustomerAddress>;
remove(params: ComposableFunctionArgs<UseAddressesParamsInput>): Promise<boolean>;
}
```
## Examples

### Loading addresses

Loading customer addresses on client side using the `onMounted` Composition API hook:

```typescript
import { onMounted, ref } from '@nuxtjs/composition-api';
import { useAddresses } from '~/composables';

export function {
setup() {
const { load } = useAddresses();
const addresses = ref([]);

onMounted(async () => {
addresses.value = await load();
});
}
}
```

### Saving an address

Save a new customer address using an event handler/function:

```typescript
import { ref, useFetch } from '@nuxtjs/composition-api';
import { useAddresses, UseAddressesParamsInput } from '~/composables';

export default {
setup(props) {
const { error, load } = useAddresses();
const addresses = ref([]);

useFetch(async () => {
addresses.value = await load();
});

const onSaveAddress = async (input: UseAddressesParamsInput) => {
const newAddress = await save(input);

if (error.value.save) {
// handle saving error
}

addresses.value.push(newAddress);
};
}
}
```

### Updating an address

Update a customer address using an event handler/function:

```typescript
import { ref, useFetch } from '@nuxtjs/composition-api';
import { useAddresses, UseAddressesParamsInput } from '~/composables';

export default {
setup(props) {
const { error, load, update } = useAddresses();
const addresses = ref([]);

useFetch(async () => {
addresses.value = await load();
});

const onUpdateAddress = async (input: UseAddressesParamsInput) => {
const updatedAddress = await update(input);

if (error.value.update) {
// handle updating error
}

addresses.value = addresses.value.map((address) => {
if (address.id === updatedAddress.id) {
return updatedAddress;
}

return address;
});
};
}
}
```

### Removing an address

Remove a customer address using event handler/function:

```typescript
import { ref, useFetch } from '@nuxtjs/composition-api';
import { useAddresses, UseAddressesParamsInput } from '~/composables';

export default {
setup(props) {
const { error, load, remove } = useAddresses();
const addresses = ref([]);

useFetch(async () => {
addresses.value = await load();
});

const onRemoveAddress = async (input: UseAddressesParamsInput) => {
const wasRemoved = await remove(input);

if (error.value.remove || !wasRemoved) {
// handle removing error
}

addresses.value = addresses.value.filter((address) => {
return address.id !== input.address.id;
});
};
}
}
```


75 changes: 75 additions & 0 deletions docs/composition/useApi.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# useApi composable

`useApi` composable allows to execute received GraphQL query with optional variables and headers and returns the result.

## API
`useApi` composable returns the following properties:

- `query` - function that executes a GraphQL query and handle its error and result
- `mutate` - function that executes received GraphQL Mutation with optional variables and headers and returns the result.

## Interfaces

```ts
type FetchPolicy = 'cache-first' | 'network-only' | 'cache-only' | 'no-cache' | 'standby';

type Variables = {
[key: string]: any;
};

type Error = {
message: string;
locations?: {
line: number;
column: number;
}[];
path?: string[];
extensions?: any;
};

type Request = <DATA, VARIABLES extends Variables = Variables>(
request: string,
variables?: VARIABLES,
fetchPolicy?: FetchPolicy,
) => Promise<{ data: DATA, errors: Error[] }>;

interface UseApiInterface {
query: Request;
mutate: Request;
}
```

## Example

Execute a GraphQL query to get cart price:

```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' }
);
}
}
};
```

68 changes: 68 additions & 0 deletions docs/composition/useBilling.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# useBilling composable

`useBilling` composable allows loading and manipulating billing information of the current user.

## API
`useBilling` composable returns the following properties:

- `load` - function that loads the billing information.
- `save` - function that Saves the billing information.
- `error` - ref that contains an errors from the composable methods
- `loading` - ref that contains information whether any of the composable methods is loading

## Interfaces

```ts
/**
* Almost every method is extending this type
*/
type ComposableFunctionArgs<T> = T & {
customQuery?: CustomQuery;
customHeaders?: CustomHeaders;
};

interface UseBillingError {
load: Error | null;
save: Error | null;
}

type UseBillingLoadParams = ComposableFunctionArgs<{}>;

type UseBillingSaveParams = ComposableFunctionArgs<{
billingDetails: BillingDetails;
}>;

interface UseBillingInterface {
load(params?: UseBillingLoadParams): Promise<BillingCartAddress | null>;
save(params: UseBillingSaveParams): Promise<BillingCartAddress | null>;
error: Readonly<Ref<UseBillingError>>;
loading: Readonly<Ref<boolean>>;
}
```

## Example

Load user's billing information and handle the form submit:

```ts
import useBilling from '~/modules/checkout/composables/useBilling';

const { save, load } = useBilling();

onMounted(async () => {
const billingInformation = await load();
});

const handleAddressSubmit = (reset: () => void) => async () => {
const billingDetailsData = {
billingDetails: {
customerAddressId: addressId,
sameAsShipping: false,
save_in_address_book: false,
},
};

await save(billingDetailsData);
};
```

Loading

0 comments on commit db2f054

Please sign in to comment.