Документація

Повний guest flow

1. На product detail додай у кошик productId, optional configurationId, configurationLabel, price і quantity.
2. На checkout згенеруй checkoutKey і opaque guestToken, передай customer payload та basket lines у useCheckout().createOrder().
3. Order створюється зі статусом NEW і payment PENDING; кнопка оплати викликає useCheckout().payOrder().
4. Після checkout веди покупця на /orders/:id/:token і став Referrer-Policy: no-referrer.
5. SHOP_ADMIN або unscoped ORDER_MANAGER рухає order у Kanban: PAID -> PROCESSING -> SHIPPED -> COMPLETED або REFUND/CANCELLED.

Product-detail add-to-cart приклад:

Order status page приклад:

Admin Kanban route/API:

Inventory mode

• Shop inventory mode налаштовується в marketing /shops: TRACKED або UNTRACKED.
• Джерело залишку одне: configuration stock override, або product stock fallback, або unmanaged null.
• Stock атомарно перевіряється і списується тільки коли payment стає PAID.
• UNTRACKED робить storefront availability оптимістичною і не списує stock під час payment.

useConfig

Глобальний composable конфігурації storefront. Зберігає locale через useState для синхронності SSR/CSR.

• `locale` - Ref<string> з поточним значенням локалі
• `setLocale(locale)` - оновлює locale і тригерить watch-refetch у composables

useCategories

Async composable над shared storefront client. Shop не передається з фронта: контекст уже резолвиться на бекенді через publicToken.

• `tree` - готове nested дерево категорій з API
• `pending` - стан завантаження
• `error` - стан помилки
• `refresh` - ручний refetch

TS interface і приклад формату документа, який повертається у tree:

useProductFilters

Loads available filters for current keyed useProducts() query state.

• Without params it reads category/filters/search from useProducts() state (same key).
• За потреби можна перевизначити categorySlug/categoryId через params.

useCatalogScopeFilters

Shortcut composable for catalog scope filters (current category + descendants) with optional parent inheritance.

• Always requests scope=catalog and is intended for catalog-facing filters UI.
• inheritParent defaults to true and can be overridden when needed.
• disableMode keeps filters visible, adds filterItem.disabled/value.disabled, and marks value disabled when not selected with count=0.

useProductFilter

Composable для одного фільтра: готує values із selected/disabled станами і перемикає значення через useProductsQuery().

• `values` - значення фільтра з selected/disabled станами для UI.
• `toggle(valueSlug)` перемикає значення; `clear()` очищає цей фільтр.

useProducts

Loads product list from a keyed query instance (category/filters/sort/page/perPage/search).

• Without params it uses its keyed local state (default key: storefront:products:catalog).
• Повертає items, total, page і perPage для pagination UI.
• Supports sort: updated-desc | updated-asc | created-desc | created-asc | price-desc | price-asc.

Typical flow: useProducts() mutates query state, and useProductFilters()/useProducts() refetch from the same key.

useProduct

Loads one published product by storefront slug through the public storefront token.

• `slug` is required and maps to GET /api/storefront/products/:productSlug.
• `product.characteristics` contains ready UI characteristics derived from product filter values.
• Product descriptions stay in `product.translations[*].descriptionHtml` and follow the active locale.

useProductQuickSelection

Керує швидким вибором значень у товарі та обчислює активну конфігурацію, ціну, стару ціну, кількість і доступні картинки.

• За замовчуванням вибирає найдешевшу доступну конфігурацію; стратегія `FIRST` вибирає першу доступну.
• Порожні overrides успадковують значення товару, а `stockQty = null` означає, що кількість не менеджиться і конфігурація доступна.
• `selectedConfiguration` містить стабільний UUID вибраної конфігурації, а `prices` надає ефективні значення для всіх комбінацій.
• У межах правила картинки умови працюють як AND, між правилами як OR; неповні правила не обмежують невказані фільтри.

useBasket

Client-side basket composable with useState source of truth, localStorage persistence, and product/configuration line identity.

• Hydrates basket from localStorage on client mount only (no server reads).
• Supports isolated baskets via storageKey, for example basket:default or basket:shop-123.
• lineId is productId:configurationId; use it for quantity changes and removal.

useCheckout

Action composable for storefront guest orders: create order, load status by opaque token, and trigger virtual payment.

• `createOrder(payload)` creates order + payment and returns `{ order, guestToken }`.
• `getOrder(orderId, guestToken)` loads the public order status page data.
• `payOrder(orderId, guestToken)` triggers the virtual payment provider and returns the updated order.

useCatalogSearch

Локальний пошук товарів з debounce, SKU-префіксами і select(), який оновлює keyed catalog state.

• `term` зберігається локально і не пишеться в query.search.
• `select(item)` очищає пошук і перемикає категорію в useProductsQuery().