orionplace-react 0.1.0 → 0.2.1

package/templates/components/orionplace/cart/StorefrontCart.README.md

@@ -0,0 +1,281 @@
+# StorefrontCart · React
+
+## English
+
+Complete cart and checkout composition with items, unavailable products,
+addresses, delivery groups, payment, promo codes and order creation.
+
+## Data and server rendering
+
+`initialData` is the verified `page_data` returned by `cart_guest_get`. Passing
+it renders the cart in the first server response and skips the automatic browser
+load by default. Without `initialData`, the component calls `onRequest` with
+`cart_guest_get` after hydration. Set `loadOnMount` explicitly when the host
+needs to refresh a server snapshot or keep an empty controlled preview.
+
+Every request is passed to `onRequest` with its exact endpoint, request data,
+route parameters when required and an `AbortSignal`. The callback returns
+`page_data` for `cart_guest_get`, an `IOrderCreated` value for `orders_create`,
+an array for a delivery-method or pickup-point load, and may return no value for
+confirmed mutations. A load replaces the complete cart snapshot, updates the
+shared cart-position counter and reconciles `cart_counts` in ordinary, featured
+and already loaded variant products.
+
+The component aborts its active request when it unmounts or authentication
+changes. An authentication change clears the previous customer snapshot and
+loads the cart again. It does not start requests or access browser globals during
+server rendering.
+
+## Cart changes and refresh safety
+
+Quantity, item, option, address, payment, recipient, comment, delivery and promo
+changes first send their mutation and then reload `cart_guest_get`. Once the
+mutation succeeds, a later refresh failure sets `needsRefresh`, preserves the
+visible snapshot and blocks further mutations. The customer can use Refresh;
+the next successful full load clears that block. The confirmed mutation is never
+sent again just to retry its refresh.
+
+Clear shows a confirmation and calls `cart_guest_clean` once. A confirmed clear
+removes the local cart data, sets the shared position count to zero and clears
+cart values from cached product cards. A guest may still change cart items. A
+guest's Checkout action calls `onRequireSignIn` with the localized cart return
+address. Without that callback it opens the localized profile route with the
+cart address in `redirect`. Promo codes also need an account
+(`marketing_promo_promo_apply` answers a guest with HTTP 401), so a guest sees
+“Sign in to apply a promo code” instead of the promo-code form; it starts the
+same sign-in.
+
+Signed-in customers choose an address before Checkout becomes available.
+Checkout groups `cart_data` by the store supplying each item. Every physical
+group has its own `CartDeliverySelector`; a store with `virtual_goods = true`
+is labelled as digital and needs no delivery choice. Several groups receive
+numbered shipment titles and a localized split-order notice. Product option
+groups stay attached to their `CartLineItem`.
+
+Totals always show goods, delivery and the final amount in the selected
+currency. Regular, promo and delivery discount rows appear only when their
+current-currency value is greater than zero. An applied promo remains visible
+with its removal action even when its item discount is zero, as with free
+shipping. A free-shipping code makes delivery free only for the shipments that
+hold a product it covers.
+
+A promo code counts over the whole cart: a percentage code takes its share off
+every product it covers (at most the promotion's maximum discount), and a fixed
+code's amount is taken once off the covered products together. When
+`marketing_promo_promo_apply` refuses a code, the reason appears under the
+promo-code form instead of the cart's general error, and the cart's items and
+prices stay as they were: a thrown error with non-empty `fields` for an unknown
+or no longer valid code, or, when the code gives this cart nothing, the reason
+from `data.promo_notice` (the response's `page_data`) with, for `below_minimum`,
+the minimum order and how much more the covered products must cost
+(`missing_amount`). In `cart_guest_get`, `cart.promo_notice` explains the code
+the cart holds. With `is_removed: false` the code stays attached but gives no
+discount now, for example when the products it covers cost less together than
+its minimum; the reason appears under the code. With `is_removed: true` the cart
+removed the code named in `promocode`, for example after it expired or reached
+its use limit, and shows “Promo code SAVE10 was removed from the cart.” with the
+reason. A known `reason` is written with the package's own text (`promoReasons`
+in `cartLabels.ts`); any other reason shows OrionMarketplace's `message`. The notice
+disappears after the next successful apply or removal; a backend that sends no
+`promo_notice` shows none. The minimum and the missing amount are dollar
+amounts: the catalog's dollar prices decide whether a code applies, so in
+another currency they read “$ 544 ≈ 40 256 ₽” (dollars, then the conversion) and
+in dollars “$ 544”. A notice with a `currency_ids` list appears only while one
+of those currencies is selected (`null` means every currency), for example a
+fixed code that takes $10 off in dollars but nothing in rubles (`too_small`);
+checkout in such a currency does not use the code. `nothing_to_ship` keeps a
+free-shipping code attached when every shipment it covers already ships for
+free.
+
+An error a cart action returns (an option, a delivery, a promo code) is shown at the top of the cart; when the customer acted further down the page, the cart scrolls it into view (`revealNotice()`, instantly with reduced motion), so a refused option such as “The package is too large. Choose another option.” is never out of sight.
+
+## Order creation
+
+The order action becomes available when a payment is selected, every
+physical shipment has a delivery method and every required option group of its
+items is filled (`option_group_required`: the text, the file or at least one
+chosen option; `cartRequiredOptionsFilled()`). It calls `orders_create` only once.
+A valid positive `order_id` clears the cart state and displays the order link
+and `PaymentPanel` when a payment link is returned. When the backend placed the
+order but the payment provider gave no link, the answer carries
+`payment_error` with an empty `link`: the cart shows that reason in “The order
+is placed, but the payment link could not be created…” and links to the order,
+where the customer pays later.
+
+For a rejected order whose thrown error has non-empty `fields` and
+`data.reboot = true`, the component reloads the changed cart before allowing
+another attempt. Other field errors remain ordinary correctable failures. A
+transport error or a response without a valid order ID can follow a committed
+order, so the component blocks replay and tells the customer to check order
+history. `onOpenOrder` handles the PaymentPanel status action; without it the
+browser opens the localized order page.
+
+`addressFormProps` supplies address search and save operations.
+`onRequestSecondaryVariants` supplies option-product variant loading.
+`onDataChange`, `onAddressSaved` and `onOrderCreated` notify the host after the
+corresponding confirmed state change. Source is maintained in
+`components/orionplace/cart/StorefrontCart.tsx`; the primary physical response
+interface is `interfaces/orionplace/cart/ICartData.ts`.
+
+### Props
+
+| Prop                                                                                                         | Meaning                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `initialData?: { cart: ICartSummary; cart_data: IProduct[] \| ICartDelivery[]; will_not_ship: IProduct[]; }` | Server-provided initial data used for the first render and hydration.                                         |
+| `initialError?: string`                                                                                      | Server-provided initial error used for the first render and hydration.                                        |
+| `loadOnMount?: boolean`                                                                                      | Starts the load callback after hydration when server data was not supplied.                                   |
+| `addressFormProps?: Omit<AddressFormProps, "onSaved" \| "onCancel">`                                         | Props forwarded to the address form child component.                                                          |
+| `productHref?: (productId: number, locale: string) => string`                                                | Builds the product destination from the callback arguments.                                                   |
+| `browseHref?: (locale: string) => string`                                                                    | Builds the browse destination from the callback arguments.                                                    |
+| `ordersHref?: (locale: string, orderId?: number) => string`                                                  | Builds the orders destination from the callback arguments.                                                    |
+| `onRequest: (action: StorefrontCartRequestAction) => Promise<unknown> \| unknown`                            | Called when the component emits its typed API action. The callback payload is shown in its type.              |
+| `onRequireSignIn?: (returnHref: string) => void`                                                             | Called when the visitor must sign in before continuing. The callback payload is shown in its type.            |
+| `onOpenOrder?: (orderId: number) => void`                                                                    | Called when the visitor opens an order. The callback payload is shown in its type.                            |
+| `onDataChange?: (data: StorefrontCartData \| undefined) => void`                                             | Called when the component has a new confirmed data snapshot. The callback payload is shown in its type.       |
+| `onAddressSaved?: (addresses: IUserAddress[]) => void`                                                       | Called when a delivery address has been saved and can be selected. The callback payload is shown in its type. |
+| `onRequestSecondaryVariants?: (request: IProductSecondaryVariantRequest) => void`                            | Passes the product ID in `product`, product group ID in `productGroup` and primary variant in `variant` when its secondary variants need loading. The application loads them and supplies them to the product store. |
+| `onOrderCreated?: (order: IOrderCreated) => void`                                                            | Called when checkout creates an order successfully. The callback payload is shown in its type.                |
+
+## Русский
+
+Компонент объединяет корзину и оформление заказа: товары, недоступные позиции,
+адреса, отправления, доставку, оплату, промокод и создание заказа.
+
+### Данные и серверный рендеринг
+
+`initialData` содержит проверенное `page_data` ответа `cart_guest_get`. С этими
+данными корзина попадает в первый HTML-ответ сервера, а автоматическая загрузка
+в браузере по умолчанию не выполняется. Без `initialData` компонент после
+гидратации вызывает `onRequest` для `cart_guest_get`. Свойство `loadOnMount`
+позволяет явно обновить серверный снимок или оставить управляемый пример без
+запроса.
+
+Каждый вызов `onRequest` содержит точное имя метода, данные запроса, параметры
+пути при необходимости и `AbortSignal`. Для `cart_guest_get` обработчик
+возвращает `page_data`, для `orders_create` — `IOrderCreated`, для загрузки
+способов доставки или пунктов выдачи — массив. Подтверждённые изменения могут
+не возвращать значение. Полная загрузка заменяет снимок корзины, обновляет общий
+счётчик позиций и согласует `cart_counts` обычных, избранных и уже загруженных
+вариантов товара.
+
+При размонтировании и смене авторизации активный запрос отменяется. После смены
+авторизации снимок прежнего покупателя удаляется и корзина загружается заново.
+Во время серверного рендеринга компонент не отправляет запросы и не обращается
+к браузерным объектам.
+
+### Изменения корзины и безопасное обновление
+
+Количество, удаление, дополнения, адрес, оплата, получатель, комментарий,
+доставка и промокод сначала отправляются отдельным запросом, затем компонент
+заново вызывает `cart_guest_get`. Если изменение уже подтверждено, а обновление
+не удалось, `needsRefresh` сохраняет показанный снимок и блокирует следующие
+изменения. Кнопка «Обновить» выполняет только `cart_guest_get`; успешный ответ
+снимает блокировку. Подтверждённое изменение не отправляется повторно вместе с
+этой попыткой.
+
+Очистка требует подтверждения и один раз вызывает `cart_guest_clean`. После
+успеха локальные данные корзины и значения корзины в карточках товаров
+очищаются, а общий счётчик становится равен нулю. Гость может менять товары.
+Кнопка оформления для гостя вызывает `onRequireSignIn` и передаёт адрес возврата
+в корзину. Без этого обработчика браузер открывает локализованную страницу
+профиля с адресом корзины в `redirect`. Промокод тоже требует входа
+(`marketing_promo_promo_apply` отвечает гостю HTTP 401), поэтому вместо формы
+промокода гость видит кнопку «Войдите, чтобы применить промокод», которая
+запускает тот же вход.
+
+Авторизованный покупатель сначала выбирает адрес. При оформлении `cart_data`
+разделён на отправления по магазинам, из которых будут переданы товары. Для
+каждого физического отправления показан собственный `CartDeliverySelector`.
+Магазин с `virtual_goods = true` обозначен как электронная доставка и не
+требует её выбора. Несколько групп получают номера отправлений и понятное
+сообщение о разделённом заказе. Дополнения остаются внутри соответствующего
+`CartLineItem`.
+
+В итогах всегда показаны товары, доставка и общая сумма в выбранной валюте.
+Строки обычной скидки, скидки промокода и скидки на доставку появляются, только
+если их значение в этой валюте больше нуля. Применённый промокод и его удаление
+остаются видимыми даже при нулевой скидке на товары, например для бесплатной
+доставки. Бесплатная доставка по промокоду действует только для отправлений, в
+которых есть товар, на который распространяется код.
+
+Промокод считается по всей корзине: процентный код снимает свою долю с каждого
+товара, на который действует (не больше максимальной скидки акции), а сумма
+фиксированного кода вычитается один раз из этих товаров вместе. Если
+`marketing_promo_promo_apply` отклоняет код, причина показывается под формой
+промокода вместо общей ошибки корзины, а товары и цены корзины не меняются:
+ошибка с непустым `fields` для неизвестного или уже недействительного кода,
+либо, когда код ничего не даёт этой корзине, причина из `data.promo_notice`
+(`page_data` ответа) и для `below_minimum` минимальная сумма заказа и сколько
+ещё должны стоить товары, на которые действует код (`missing_amount`). В ответе
+`cart_guest_get` поле `cart.promo_notice` объясняет код в корзине. При
+`is_removed: false` код остаётся в корзине, но сейчас не даёт скидки, например
+товары, на которые он действует, стоят вместе меньше его минимума; причина видна
+под кодом. При `is_removed: true` корзина удалила код из `promocode`, например
+после окончания срока или исчерпания применений, и показывает «Промокод SAVE10
+удалён из корзины.» с причиной. Известная причина `reason` выводится текстом
+пакета (`promoReasons` в `cartLabels.ts`), любая другая — значением `message` от
+OrionMarketplace. Сообщение исчезает после следующего успешного применения или удаления
+кода; если бэкенд не присылает `promo_notice`, сообщения нет. Минимальная и
+недостающая суммы указаны в долларах: применяется ли код, решают долларовые цены
+каталога, поэтому в другой валюте они выглядят как «$ 544 ≈ 40 256 ₽» (доллары,
+затем пересчёт), а в долларах — «$ 544». Сообщение со списком `currency_ids`
+показывается, только пока выбрана одна из этих валют (`null` — любая валюта),
+например фиксированный код снимает $10 в долларах, но ничего в рублях
+(`too_small`); при оформлении в такой валюте код не применяется.
+`nothing_to_ship` оставляет код бесплатной доставки в корзине, когда все
+отправления, на которые он действует, и так доставляются бесплатно.
+
+Ошибка действия в корзине (опция, доставка, промокод) показывается вверху корзины; если покупатель действовал ниже по странице, корзина прокручивает её в поле зрения (`revealNotice()`, без анимации при «уменьшении движения»), так что отказ в опции вроде «Посылка слишком большая. Выберите другой вариант.» не остаётся вне экрана.
+
+### Создание заказа
+
+Кнопка заказа становится доступной после выбора оплаты, способа доставки для
+каждого физического отправления и заполнения каждой обязательной группы опций
+его товаров (`option_group_required`: текст, файл или хотя бы одна выбранная
+опция; `cartRequiredOptionsFilled()`). `orders_create` отправляется один раз. Ответ с
+положительным `order_id` очищает корзину и показывает ссылку на заказ, а при
+наличии платёжной ссылки — `PaymentPanel`. Если бэкенд создал заказ, но
+платёжный провайдер не дал ссылку, ответ содержит `payment_error` и пустой
+`link`: корзина показывает причину в сообщении «Заказ создан, но ссылку на
+оплату получить не удалось…» и ссылку на заказ, где покупатель оплатит его
+позже.
+
+Если отклонённый запрос содержит непустой объект `fields` и
+`data.reboot = true`, компонент сначала загружает изменившуюся корзину. Другие
+ошибки полей можно исправить и повторить. После транспортной ошибки или ответа
+без корректного ID заказ уже мог быть создан, поэтому повторная отправка
+блокируется и покупателю предлагается проверить историю заказов.
+`onOpenOrder` обрабатывает проверку из `PaymentPanel`; без него браузер открывает
+локализованную страницу заказа.
+
+`addressFormProps` передаёт операции поиска и сохранения адреса.
+`onRequestSecondaryVariants` загружает варианты товаров в дополнениях.
+`onDataChange`, `onAddressSaved` и `onOrderCreated` сообщают родителю о
+подтверждённых изменениях. Исходный файл:
+`components/orionplace/cart/StorefrontCart.tsx`; основной физический интерфейс
+ответа: `interfaces/orionplace/cart/ICartData.ts`.
+
+### Свойства
+
+| Свойство                                                                                                     | Назначение                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `initialData?: { cart: ICartSummary; cart_data: IProduct[] \| ICartDelivery[]; will_not_ship: IProduct[]; }` | Начальные данные с сервера для первого рендера и гидратации.                                                  |
+| `initialError?: string`                                                                                      | Начальное значение ошибки, полученное на сервере для первого рендера и гидратации.                            |
+| `loadOnMount?: boolean`                                                                                      | Запускает загрузку после гидратации, если серверные данные не переданы.                                       |
+| `addressFormProps?: Omit<AddressFormProps, "onSaved" \| "onCancel">`                                         | Свойства, передаваемые дочернему компоненту формы адреса.                                                     |
+| `productHref?: (productId: number, locale: string) => string`                                                | Строит адрес ссылки товара из аргументов обработчика.                                                         |
+| `browseHref?: (locale: string) => string`                                                                    | Строит адрес ссылки поиска товаров из аргументов обработчика.                                                 |
+| `ordersHref?: (locale: string, orderId?: number) => string`                                                  | Строит адрес ссылки заказов из аргументов обработчика.                                                        |
+| `onRequest: (action: StorefrontCartRequestAction) => Promise<unknown> \| unknown`                            | Вызывается, когда компонент отправляет типизированное действие API. Данные обработчика указаны в его типе.    |
+| `onRequireSignIn?: (returnHref: string) => void`                                                             | Вызывается, когда покупателю нужно войти перед продолжением. Данные обработчика указаны в его типе.           |
+| `onOpenOrder?: (orderId: number) => void`                                                                    | Вызывается, когда покупатель открывает заказ. Данные обработчика указаны в его типе.                          |
+| `onDataChange?: (data: StorefrontCartData \| undefined) => void`                                             | Вызывается, когда компонент получил новый подтверждённый набор данных. Данные обработчика указаны в его типе. |
+| `onAddressSaved?: (addresses: IUserAddress[]) => void`                                                       | Вызывается, когда адрес доставки сохранён и его можно выбрать. Данные обработчика указаны в его типе.         |
+| `onRequestSecondaryVariants?: (request: IProductSecondaryVariantRequest) => void`                            | Передаёт ID товара в `product`, ID группы товаров в `productGroup` и основной вариант в `variant`, когда для него нужно загрузить дополнительные варианты. Приложение загружает и передаёт их в хранилище товаров. |
+| `onOrderCreated?: (order: IOrderCreated) => void`                                                            | Вызывается, когда оформление успешно создаёт заказ. Данные обработчика указаны в его типе.                    |
+
+## Loading and retries / Загрузка и повтор
+
+The cart shows loading until a snapshot or a request error is available. After a failed load, Refresh retries the request.
+
+Пока нет данных корзины или ошибки запроса, отображается загрузка. После ошибки кнопка «Обновить» повторяет загрузку.