orionplace-react 0.1.0 → 0.2.0

package/templates/components/orionplace/orders/OrderPaymentForm.README.md

@@ -0,0 +1,92 @@
+# OrderPaymentForm · React
+
+## English
+
+`OrderPaymentForm` lets a customer choose one payment method that the
+application loaded for an existing order. `methods` contains the response from
+`orders_payment_methods_get`. Each choice uses its localized `payment_name` and
+falls back to `#<id>` when no translation is available.
+
+The form starts with no method selected. Continue stays disabled until the
+customer chooses an ID that remains present in `methods`, then calls `onSubmit`
+with that numeric payment-method ID. If a refreshed method list removes the
+selection, the form clears it. `pending` disables selection, Continue and
+Cancel; a rejected save can therefore clear `pending` without losing a still
+available selection. Cancel calls `onCancel` with no data. An empty method list
+shows the unavailable message and cannot submit.
+
+The parent saves the choice with `orders_payment_methods_set`, using the order
+ID and the emitted payment ID. Source is maintained in
+`components/orionplace/orders/OrderPaymentForm.tsx`; payment methods are defined
+in `interfaces/orionplace/cart/ICartData.ts`.
+
+### Props
+
+| Prop                                   | Meaning                                                                                               |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `methods: IPaymentMethod[]`            | Payment or delivery methods available for the current action.                                         |
+| `pending?: boolean`                    | Shows the loading state and blocks duplicate actions.                                                 |
+| `onSubmit?: (payment: number) => void` | Passes the selected available payment method ID on form confirmation. The application saves the order’s payment choice. |
+| `onCancel?: () => void`                | Called when the visitor cancels the current form or action. The callback has no payload.              |
+
+## Русский
+
+`OrderPaymentForm` позволяет покупателю выбрать один способ оплаты,
+который приложение загрузило для существующего заказа. `methods`
+содержит ответ `orders_payment_methods_get`. Для каждого варианта
+показывается локализованное `payment_name`, а при его отсутствии —
+`#<id>`.
+
+При открытии способ не выбран. Кнопка «Продолжить» недоступна,
+пока покупатель не выберет ID, который всё ещё есть в `methods`. Затем
+вызывается `onSubmit` с числовым ID способа оплаты. Если после
+обновления списка выбранного варианта в нём нет, форма сбрасывает выбор.
+`pending` блокирует список, продолжение и отмену; поэтому после ошибки
+сохранения родитель может снять `pending`, не теряя доступный выбор.
+Отмена вызывает `onCancel` без данных. Пустой список показывает сообщение о
+недоступности и не может быть отправлен.
+
+Родитель сохраняет выбор через `orders_payment_methods_set`, передавая ID заказа
+и полученный ID оплаты. Исходный файл:
+`components/orionplace/orders/OrderPaymentForm.tsx`; способы оплаты описаны в
+`interfaces/orionplace/cart/ICartData.ts`.
+
+### Свойства
+
+| Свойство                               | Назначение                                                                                                    |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `methods: IPaymentMethod[]`            | Способы оплаты или доставки, доступные для текущего действия.                                                 |
+| `pending?: boolean`                    | Показывает загрузку и блокирует повторные действия.                                                           |
+| `onSubmit?: (payment: number) => void` | Передаёт ID выбранного доступного способа оплаты при подтверждении формы. Приложение сохраняет выбор для заказа. |
+| `onCancel?: () => void`                | Вызывается, когда покупатель отменяет текущую форму или действие. Обработчик не получает данные.              |
+## Response fields and application actions
+
+The following tables describe the response and the supplied composition’s follow-up actions. The framework-specific props and events above identify which work belongs to the component and which belongs to its parent.
+
+### English
+
+### From available methods to a payment request
+
+| Field or condition | Meaning and application action |
+| --- | --- |
+| `orders_payment_methods_get` | The parent sends the selected order ID as URL `order_id`. It retains that order ID separately and passes `Object.values(page_data)` to the form’s `methods` prop. |
+| `methods[].id` and `locale` | Use the returned method ID. The name comes from `locale` in the current language with the normal language fallback; an unavailable name displays the method’s ID. |
+| Empty `methods` / no selection | An empty list shows that payment is unavailable. Initially no method is selected; the confirmation button stays disabled until a choice is made. |
+| `onSubmit` | Calls the callback with the selected numeric method ID. The parent validates it against the loaded methods, then sends `order: savedOrderId` and `payment: methodId` to `orders_payment_methods_set`. |
+| Returned `link` and `link_type` | These describe the next payment page. The parent supplies them to `PaymentPanel` when appropriate and reloads `profile_orders_get`. Empty link data can mean no external page is needed; only the refreshed payment/order status confirms the result. |
+| `onCancel` / `pending` | onCancel runs without arguments and asks the parent to dismiss the form. Pending disables selection and both buttons. A failed save keeps the form and its selection available for correction. |
+
+### Русский
+
+### От доступных способов к запросу оплаты
+
+| Поле или условие | Значение и действие приложения |
+| --- | --- |
+| `orders_payment_methods_get` | Родитель передаёт ID выбранного заказа в URL `order_id`. Этот ID сохраняется отдельно, а в свойство формы `methods` передаётся `Object.values(page_data)`. |
+| `methods[].id` и `locale` | Используйте ID способа из ответа. Название берётся из `locale` на текущем языке с обычным выбором доступного перевода; если названия нет, выводится ID способа. |
+| Пустой `methods` / нет выбора | Пустой список сообщает о недоступности оплаты. Изначально способ не выбран; кнопка подтверждения отключена до выбора. |
+| `onSubmit` | Передаёт числовой ID выбранного способа. Родитель проверяет его среди загруженных способов, затем отправляет `order: savedOrderId` и `payment: methodId` в `orders_payment_methods_set`. |
+| Полученные `link` и `link_type` | Описывают следующую страницу оплаты. Родитель при необходимости передаёт их в `PaymentPanel` и загружает `profile_orders_get`. Пустая ссылка может означать, что внешняя страница не нужна; результат подтверждает обновлённое состояние платежа/заказа. |
+| `onCancel` / `pending` | Cancel без данных просит родителя закрыть форму. Pending блокирует выбор и обе кнопки. Ошибка сохранения оставляет форму и выбранный способ для исправления. |
+
+[English guide](https://orionmarket.place/en/sandbox/components/react/order-payment-form) · [Русский](https://orionmarket.place/ru/sandbox/components/react/order-payment-form)

package/templates/components/orionplace/orders/OrderPaymentForm.module.css

@@ -0,0 +1,105 @@
+/* Payment method form of an unpaid order, as Nuxt `OrderPaymentForm`. */
+.root {
+  display: flex;
+  box-sizing: border-box;
+  min-width: 0;
+  flex-direction: column;
+  gap: 0.75rem;
+  padding: 1.25rem;
+  border: 1px solid var(--orionplace-border);
+  color: var(--orionplace-text);
+  background: transparent;
+  font: inherit;
+}
+
+.root h3,
+.root p {
+  margin: 0;
+}
+
+.root h3 {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  color: var(--orionplace-muted);
+  font-size: 0.75rem;
+  line-height: 1rem;
+  font-weight: 500;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.root p {
+  color: var(--orionplace-text);
+  font-size: 0.875rem;
+  line-height: 1.5rem;
+}
+
+/* Full-width buttons on a phone, one row from 592px of the orders' width. */
+.actions {
+  display: grid;
+  gap: 0.5rem;
+}
+
+.actions button {
+  display: inline-flex;
+  box-sizing: border-box;
+  height: 2.75rem;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  padding: 0 1.5rem;
+  border: 1px solid var(--orionplace-text);
+  border-radius: 0;
+  color: var(--orionplace-text);
+  background: transparent;
+  font: inherit;
+  font-size: 0.75rem;
+  line-height: 1rem;
+  font-weight: 500;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  cursor: pointer;
+  outline: none;
+}
+
+.actions button:focus-visible {
+  background: var(--orionplace-hover);
+}
+
+@media (hover: hover) {
+  .actions button:hover:not(:disabled) {
+    background: var(--orionplace-hover);
+  }
+}
+
+.actions button:disabled {
+  cursor: not-allowed;
+  opacity: 0.4;
+}
+
+.actions .primary {
+  border-color: var(--orionplace-accent);
+  color: var(--orionplace-surface);
+  background: var(--orionplace-accent);
+}
+
+.actions .primary:focus-visible {
+  background: var(--orionplace-accent);
+  opacity: 0.85;
+}
+
+@media (hover: hover) {
+  .actions .primary:hover:not(:disabled) {
+    background: var(--orionplace-accent);
+    opacity: 0.85;
+  }
+}
+
+@container (min-width: 592px) {
+  .actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.75rem;
+  }
+}

package/templates/components/orionplace/orders/OrderPaymentForm.tsx

@@ -0,0 +1,90 @@
+'use client';
+
+import { useEffect, useMemo, useState, type FormEvent } from 'react';
+import { useOrionplaceSelections } from '@/providers/OrionplaceProvider';
+import type { IPaymentMethod } from '@/interfaces/orionplace/cart/ICartData';
+import { featureLabels } from '@/lib/orionplace/featureLabels';
+import { orderLabels } from '@/lib/orionplace/orderLabels';
+import { getAvailableNestedValueFromObject } from '@/lib/orionplace/presentation';
+import { OrionplaceSelect } from '@/components/orionplace/shared/OrionplaceSelect';
+import styles from './OrderPaymentForm.module.css';
+
+export interface OrderPaymentFormProps {
+  methods: IPaymentMethod[];
+  pending?: boolean;
+  onSubmit?: (payment: number) => void;
+  onCancel?: () => void;
+}
+
+export function OrderPaymentForm({
+  methods,
+  pending = false,
+  onSubmit,
+  onCancel,
+}: OrderPaymentFormProps) {
+  const locale = useOrionplaceSelections((state) => state.localeCode);
+  const labels = orderLabels(locale);
+  const common = featureLabels(locale);
+  const [selected, setSelected] = useState('0');
+  const options = useMemo(() => ({
+    0: labels.choosePayment,
+    ...Object.fromEntries(methods.map((method) => [
+      method.id,
+      getAvailableNestedValueFromObject(
+        method.locale,
+        locale,
+        'payment_name',
+      ) || `#${method.id}`,
+    ])),
+  }), [labels.choosePayment, locale, methods]);
+  const selectedId = Number(selected);
+  const validSelection = methods.some((method) => method.id === selectedId);
+
+  useEffect(() => {
+    if (selected !== '0' && !validSelection) {
+      setSelected('0');
+    }
+  }, [methods, selected, validSelection]);
+
+  function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!pending && validSelection) {
+      onSubmit?.(selectedId);
+    }
+  }
+
+  return (
+    <form
+      className={styles.root}
+      aria-busy={pending}
+      data-feature-part="OrderPaymentForm"
+      onSubmit={submit}
+    >
+      <h3>{labels.payment}</h3>
+      {!methods.length ? (
+        <p>{labels.unavailable}</p>
+      ) : (
+        <OrionplaceSelect
+          options={options}
+          label={labels.paymentMethod}
+          value={selected}
+          disabled={pending}
+          required
+          onValueChange={setSelected}
+        />
+      )}
+      <div className={styles.actions}>
+        <button
+          type="submit"
+          className={styles.primary}
+          disabled={pending || !validSelection}
+        >
+          {common.continue}
+        </button>
+        <button type="button" disabled={pending} onClick={() => onCancel?.()}>
+          {common.cancel}
+        </button>
+      </div>
+    </form>
+  );
+}

package/templates/components/orionplace/orders/StorefrontOrders.README.md

@@ -0,0 +1,131 @@
+# StorefrontOrders · React
+
+## English
+
+`StorefrontOrders` renders order history and coordinates its API actions.
+`onLoad` receives `profile_orders_get` with the selected `order_tab` and page.
+`orderId` replaces that tab filter with `filters.id`, opens the matching order
+details and shows a link to all orders. A new `orderId` loads that order (or
+the list) and clears a reorder notice, an open confirmation and a payment form.
+`initial` provides an SSR-ready page;
+otherwise `loadOnMount` starts the request after hydration. A tab starts again
+at page one, pagination sends the selected page, and Refresh retains it.
+
+Each card derives its order and payment badges from the physical status,
+shipment dates, paid amount and `pay_on_delivery`. It displays fixed-size item
+thumbnails, unique delivery-method names, shipment progress, expected dates and
+the complete price breakdown returned for the selected currency. Zero-valued
+discount, paid, due and refund rows are omitted. A delivery amount still being
+calculated is labelled instead of formatted as money. The Details disclosure
+uses `OrderDetails` for shipment items, options, returns and files.
+
+Cancel is available only for a created, unpaid order and requires confirmation.
+It sends `orders_cancel` with the order ID in `path.order_id`, then reloads the
+current page. Repeat also requires confirmation, sends `orders_repeat` with
+`{ order: id }`, and calls `cart_guest_get` through `onReadCart` when supplied.
+That response updates the separate product store's cart counter and cached
+product quantities. A successful repeat disables another repeat and shows the
+cart link.
+
+Pay first calls `orders_payment_methods_get` with `path.order_id`. The verified
+`OrderPaymentForm` then calls `orders_payment_methods_set` with the order and
+selected payment IDs. Its returned link opens in `PaymentPanel`, and the current
+orders page reloads. Checking or closing that panel reloads orders; closing does
+not confirm payment.
+
+Downloads route product, option and customer group files to their exact
+endpoints and include `filename` for the host to save the successful response.
+While one request is active, mutations and downloads are disabled. If a
+mutation succeeds but its required order refresh fails, a visible refresh
+warning blocks another mutation until Refresh succeeds. Every request receives
+an `AbortSignal`; unmounting cancels the active request.
+
+Source is maintained in
+`components/orionplace/orders/StorefrontOrders.tsx`; the order contract is in
+`interfaces/orionplace/orders/IOrderHistory.ts`.
+
+### Props
+
+| Prop                                                                                                                                                                              | Meaning                                                                                                  |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `orderId?: number`                                                                                                                                                                | ID of the order handled by StorefrontOrders.                                                             |
+| `initial?: { data: IOrder[]; rpag: IApiPagination; }`                                                                                                                             | Server-provided initial data used for the first render and hydration.                                    |
+| `initialError?: string`                                                                                                                                                           | Server-provided initial error used for the first render and hydration.                                   |
+| `initialTab?: EOrderTab`                                                                                                                                                          | Server-provided initial tab used for the first render and hydration.                                     |
+| `loadOnMount?: boolean`                                                                                                                                                           | Starts the load callback after hydration when server data was not supplied.                              |
+| `ordersHref?: (locale: string) => string`                                                                                                                                         | Builds the orders destination from the callback arguments.                                               |
+| `catalogHref?: (locale: string) => string`                                                                                                                                        | Builds the catalog destination from the callback arguments.                                              |
+| `cartHref?: (locale: string) => string`                                                                                                                                           | Builds the cart destination from the callback arguments.                                                 |
+| `onLoad: (action: OrdersLoadAction) => Promise<OrdersPage> \| OrdersPage`                                                                                                         | Called when the component needs its primary data. The callback payload is shown in its type.             |
+| `onCancel?: (action: OrderCancelAction) => Promise<void> \| void`                                                                                                                 | Called when the visitor cancels the current form or action. The callback payload is shown in its type.   |
+| `onRepeat?: (action: OrderRepeatAction) => Promise<void> \| void`                                                                                                                 | Called when the visitor repeats an order. The callback payload is shown in its type.                     |
+| `onReadCart?: (action: OrderCartReadAction) => Promise<CartPage> \| CartPage`                                                                                                     | Called when the refreshed cart must be loaded. The callback payload is shown in its type.                |
+| `onLoadPaymentMethods?: (action: OrderPaymentMethodsAction) => Promise<Record<string, IPaymentMethod> \| IPaymentMethod[]> \| Record<string, IPaymentMethod> \| IPaymentMethod[]` | Called when available payment methods must be loaded. The callback payload is shown in its type.         |
+| `onSetPayment?: (action: OrderPaymentSetAction) => Promise<IStorefrontPayment> \| IStorefrontPayment`                                                                             | Called when the visitor confirms an order payment method. The callback payload is shown in its type.     |
+| `onDownload?: (action: OrderDownloadAction) => Promise<void> \| void`                                                                                                             | Called when the visitor requests the selected protected file. The callback payload is shown in its type. |
+| `onPageChange?: (page: number) => void`                                                                                                                                           | Called when the visitor requests another page. The callback payload is shown in its type.                |
+| `onTabChange?: (tab: EOrderTab) => void`                                                                                                                                          | Called when the visitor selects another account tab. The callback payload is shown in its type.          |
+
+## Русский
+
+`StorefrontOrders` показывает историю заказов и связывает её действия API.
+`onLoad` получает `profile_orders_get` с выбранным `order_tab` и страницей.
+`orderId` заменяет этот фильтр на `filters.id`, открывает данные заказа и
+показывает ссылку на все заказы. `initial` передаёт страницу для серверного HTML;
+без неё `loadOnMount` запускает запрос после гидратации. Новая вкладка начинается с
+первой страницы, пагинация передаёт выбранную, а «Обновить» сохраняет её.
+
+Карточка выводит статусы заказа и оплаты из физического статуса, дат
+отправлений, оплаченной суммы и `pay_on_delivery`. В ней видны миниатюры фиксированного
+размера, уникальные названия способов доставки, ход отправки, ожидаемые даты и все
+суммы ответа в выбранной валюте. Нулевые скидки, оплаченная сумма, остаток и возвраты
+скрыты. Если стоимость доставки ещё рассчитывается, вместо денег показана эта метка.
+В раскрывающемся разделе `OrderDetails` находятся позиции отправлений, дополнения, возвраты
+и файлы.
+
+Отмена доступна только для созданного и неоплаченного заказа и требует
+подтверждения. Она передаёт `orders_cancel` с ID заказа в `path.order_id`, после чего
+заново загружает текущую страницу. Повтор также требует подтверждения, передаёт
+`orders_repeat` с `{ order: id }` и при наличии `onReadCart` вызывает `cart_guest_get`. Этот ответ
+обновляет счётчик корзины в отдельном хранилище товаров и количества в кэше
+товаров. После успешного повтора его нельзя запустить ещё раз, а на странице видна
+ссылка на корзину.
+
+Оплата сначала вызывает `orders_payment_methods_get` с `path.order_id`. Проверенная
+`OrderPaymentForm` затем вызывает `orders_payment_methods_set` с ID заказа и выбранной
+оплаты. Возвращённая ссылка открывается в `PaymentPanel`, а текущая страница заказов
+загружается заново. Проверка или закрытие этой панели обновляет заказы; закрытие само по себе
+не подтверждает оплату.
+
+Скачивания передают файлы товара, дополнения и группы по точным методам и добавляют
+`filename`, чтобы родитель сохранил успешный ответ. Пока выполняется один запрос,
+изменения и скачивания недоступны. Если изменение прошло, а обязательное обновление
+заказов завершилось ошибкой, видно предупреждение; другое изменение заблокировано, пока
+«Обновить» не завершится успешно. Каждый запрос получает `AbortSignal`; размонтирование
+отменяет активный запрос.
+
+Исходный файл:
+`components/orionplace/orders/StorefrontOrders.tsx`; контракт заказа находится в
+`interfaces/orionplace/orders/IOrderHistory.ts`.
+
+### Свойства
+
+| Свойство                                                                                                                                                                          | Назначение                                                                                                 |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `orderId?: number`                                                                                                                                                                | ID заказа, с которым работает StorefrontOrders.                                                            |
+| `initial?: { data: IOrder[]; rpag: IApiPagination; }`                                                                                                                             | Начальные данные с сервера для первого рендера и гидратации.                                               |
+| `initialError?: string`                                                                                                                                                           | Начальное значение ошибки, полученное на сервере для первого рендера и гидратации.                         |
+| `initialTab?: EOrderTab`                                                                                                                                                          | Начальное значение вкладки, полученное на сервере для первого рендера и гидратации.                        |
+| `loadOnMount?: boolean`                                                                                                                                                           | Запускает загрузку после гидратации, если серверные данные не переданы.                                    |
+| `ordersHref?: (locale: string) => string`                                                                                                                                         | Строит адрес ссылки заказов из аргументов обработчика.                                                     |
+| `catalogHref?: (locale: string) => string`                                                                                                                                        | Строит адрес ссылки каталога из аргументов обработчика.                                                    |
+| `cartHref?: (locale: string) => string`                                                                                                                                           | Строит адрес ссылки корзины из аргументов обработчика.                                                     |
+| `onLoad: (action: OrdersLoadAction) => Promise<OrdersPage> \| OrdersPage`                                                                                                         | Вызывается, когда компоненту нужны основные данные. Данные обработчика указаны в его типе.                 |
+| `onCancel?: (action: OrderCancelAction) => Promise<void> \| void`                                                                                                                 | Вызывается, когда покупатель отменяет текущую форму или действие. Данные обработчика указаны в его типе.   |
+| `onRepeat?: (action: OrderRepeatAction) => Promise<void> \| void`                                                                                                                 | Вызывается, когда покупатель повторяет заказ. Данные обработчика указаны в его типе.                       |
+| `onReadCart?: (action: OrderCartReadAction) => Promise<CartPage> \| CartPage`                                                                                                     | Вызывается, когда нужно загрузить обновлённую корзину. Данные обработчика указаны в его типе.              |
+| `onLoadPaymentMethods?: (action: OrderPaymentMethodsAction) => Promise<Record<string, IPaymentMethod> \| IPaymentMethod[]> \| Record<string, IPaymentMethod> \| IPaymentMethod[]` | Вызывается, когда нужно загрузить доступные способы оплаты. Данные обработчика указаны в его типе.         |
+| `onSetPayment?: (action: OrderPaymentSetAction) => Promise<IStorefrontPayment> \| IStorefrontPayment`                                                                             | Вызывается, когда покупатель подтверждает способ оплаты заказа. Данные обработчика указаны в его типе.     |
+| `onDownload?: (action: OrderDownloadAction) => Promise<void> \| void`                                                                                                             | Вызывается, когда покупатель запрашивает выбранный защищённый файл. Данные обработчика указаны в его типе. |
+| `onPageChange?: (page: number) => void`                                                                                                                                           | Вызывается, когда покупатель открывает другую страницу. Данные обработчика указаны в его типе.             |
+| `onTabChange?: (tab: EOrderTab) => void`                                                                                                                                          | Вызывается, когда покупатель выбирает другую вкладку аккаунта. Данные обработчика указаны в его типе.      |