# React

URL: https://theelena.me/docs/avileo/tiendas/react
Text: https://theelena.me/docs/avileo/tiendas/react.txt
Description: Usa AvileoProvider y hooks de React para catálogos y carritos públicos.
Context: environment=production; apiBaseUrl=https://tienda.theelena.me; activation=active; rubro=tiendas

# React

`@tarileo/avileo-sdk/react` adds a provider and hooks on top of TanStack Query.

## Provider

Install the provider once at the storefront root:

```tsx
import { AvileoProvider } from '@tarileo/avileo-sdk/react';

export default function StorefrontLayout({ children }: { children: React.ReactNode }) {
  return (
    <AvileoProvider baseUrl="https://tienda.theelena.me" clientKey="avileo_pk_...">
      {children}
    </AvileoProvider>
  );
}
```

You can also pass your own `queryClient` if your app already manages one.

## Main hooks

```tsx
import { useBusiness, useCatalog, useCart, useSessionSettings } from '@tarileo/avileo-sdk/react';

export function CatalogPage() {
  const { data: business } = useBusiness();
  const { data: catalog, isLoading } = useCatalog();
  const cart = useCart();
  const sessionSettings = useSessionSettings();

  if (isLoading) return <p>Loading catalog...</p>;

  return (
    <pre>
      {JSON.stringify({ business, products: catalog?.products.length, sessionSettings }, null, 2)}
    </pre>
  );
}
```

### `useBusiness`

Loads `BusinessScope.getInfo()` and returns the business public profile.

### `useCatalog(params?)`

Loads the public catalog. Accepts filters such as `search` and `categoryId`.

Pass `undefined` for empty filters:

```tsx
const params = {
  search: search.trim() || undefined,
  categoryId: selectedCategoryId === 'all' ? undefined : selectedCategoryId,
};

const catalog = useCatalog(params);
```

Use `category.id` from `catalog.data.categories` for category filters. Do not
filter by category name. Keep the category row visible even when no products
match the current search.

### `useCart`

Keeps the browser draft cart. It persists the token in `localStorage` under a namespace derived from the Client Key so different businesses do not share drafts.

Returns:

- `cart`: the current public sale or `null`;
- `isLoading` and `error`;
- `addItem`, `updateItem`, `removeItem`;
- `clear` to forget the local draft;
- `cartInstance` for advanced operations.

After `await cart.addItem(...)`, render the badge, line count, line items, and
totals from `cart.cart`. Avoid duplicate local counters; they can drift from the
SDK state.

Cart item prices come from sale item fields:

```tsx
const unitPrice = item.unitPrice ?? item.unitPriceQuoted ?? item.unitPriceFinal;
```

Use `item.subtotal` for the line total and `cart.cart.totalAmount` for the cart
total. Do not render a fallback like `S/ 0.00 c/u` when the sale item has a real
subtotal.

### `useSessionSettings`

Loads public session settings when the business supports session-based services.

## Cache by Client Key

The hooks use TanStack Query. The provider creates the `BusinessScope` with the current Client Key, and `useCart` persists the token under `avileo:cart:v2:<namespace>`, where the namespace comes from the public key. This prevents a multi-business storefront from mixing carts between Client Keys.