orionplace-react 0.1.0 → 0.2.0

package/templates/components/orionplace/units/UnitSwitcher.README.md

@@ -0,0 +1,35 @@
+# UnitSwitcher
+
+## English
+
+Shows the weight or length units from Application Load. `kind` chooses
+`weights` or `lengths` and defaults to `weights`. Selecting a unit changes
+only that unit ID and calls `onChange(unit)` with its complete object.
+The option caption uses the unit's title and symbol for the selected language.
+`label` names the field; `disabled` blocks selection.
+
+### Props
+
+| Prop                                            | Meaning                                                                                  |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `kind?: "weights" \| "lengths"`                 | Selects weight units (`weights`) or length units (`lengths`). |
+| `label?: string`                                | Visible or accessible name for the component’s main control or region.                   |
+| `disabled?: boolean`                            | Disables the component controls and prevents new actions.                                |
+| `onChange?: (unit: IAppLoadCommonUnit) => void` | Passes the selected unit object after changing `weightId` for `weights` or `lengthId` for `lengths`. Other current selections are preserved. |
+
+## Русский
+
+Показывает единицы веса или длины из ответа Application Load. `kind`
+выбирает `weights` или `lengths`; по умолчанию `weights`. Выбор меняет
+только ID соответствующей единицы и вызывает `onChange(unit)` с её
+полным объектом. Название и символ варианта берутся для выбранного языка.
+`label` задаёт название поля, `disabled` блокирует выбор.
+
+### Свойства
+
+| Свойство                                        | Назначение                                                                                       |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `kind?: "weights" \| "lengths"`                 | Выбирает единицы веса (`weights`) или длины (`lengths`). |
+| `label?: string`                                | Видимое или доступное название основного элемента компонента.                                    |
+| `disabled?: boolean`                            | Блокирует элементы компонента и новые действия.                                                  |
+| `onChange?: (unit: IAppLoadCommonUnit) => void` | Передаёт объект выбранной единицы после изменения `weightId` для `weights` или `lengthId` для `lengths`. Остальные текущие настройки сохраняются. |

package/templates/components/orionplace/units/UnitSwitcher.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+import { useOrionplaceSelections, useOrionplaceSelectionsStore } from '@/providers/OrionplaceProvider';
+import { OrionplaceSelect } from '@/components/orionplace/shared/OrionplaceSelect';
+import { getAvailableNestedValueFromObject } from '@/lib/orionplace/presentation';
+import type { IAppLoadCommonUnit } from '@/interfaces/orionplace/appBase/appLoadCommon/IAppLoadCommonUnit';
+
+export interface UnitSwitcherProps {
+  kind?: 'weights' | 'lengths';
+  label?: string;
+  disabled?: boolean;
+  onChange?: (unit: IAppLoadCommonUnit) => void;
+}
+
+export function UnitSwitcher({
+  kind = 'weights',
+  label = 'Unit',
+  disabled = false,
+  onChange,
+}: UnitSwitcherProps) {
+  const selections = useOrionplaceSelections((state) => state);
+  const store = useOrionplaceSelectionsStore();
+  const units = selections.init?.[kind] ?? {};
+  const options = Object.fromEntries(
+    Object.entries(units).map(([id, unit]) => {
+      const title = getAvailableNestedValueFromObject(
+        unit.locales,
+        selections.localeCode,
+        'title',
+      );
+      const symbol = getAvailableNestedValueFromObject(
+        unit.locales,
+        selections.localeCode,
+        'unit',
+      ) || unit.unit;
+
+      return [id, [title, symbol].filter(Boolean).join(' · ') || id];
+    }),
+  );
+
+  function selectUnit(id: string) {
+    const unit = units[id];
+    if (unit) {
+      onChange?.(unit);
+    }
+  }
+
+  return (
+    <OrionplaceSelect
+      value={kind === 'lengths' ? selections.lengthId : selections.weightId}
+      onValueChange={(id) => store.getState().setUnit(kind, id)}
+      onChange={selectUnit}
+      options={options}
+      label={label}
+      disabled={disabled}
+    />
+  );
+}

package/templates/components/orionplace/wallet/StorefrontWallet.README.md

@@ -0,0 +1,154 @@
+# StorefrontWallet · React
+
+## English
+
+`StorefrontWallet` renders the selected-currency balance, wallet top-up and the
+customer's payment history. `initialData` and `initialCategory` can render the
+first history screen on the server. Without initial data, `onLoad` receives
+`invoices_get` with the selected `wallet`, `orders` or `paid_subs` category and
+pagination after hydration. Category and page changes are reported through the
+optional route callbacks.
+
+Deposit first calls `onLoadMethods` with both delivery and balance methods
+excluded. `WalletTopUpForm` then sends the exact amount string, payment ID and
+currency ID to `onCreate`. The returned payment opens `PaymentPanel`, and the
+history switches to the wallet category at page 1, where the new invoice is
+listed; `onCategoryChange` reports the switch. Checking or closing that panel refreshes the
+history and calls `onLoadProfile`; the signed-in profile's returned wallet is
+shown immediately in `WalletBalance`.
+
+Each invoice shows its state in the reader's language, selected-currency amount,
+date, payment method, purpose, useful transaction reference and comment. Order and
+subscription payments link to their storefront records. Refunds remain inside
+their original invoice with their own state, amount, destination and
+references. The state is worded from `labels.wallet.statuses` by `status.int`,
+because the backend's `status.text` is English only; a state the labels do not
+know keeps `status.text`. A created invoice with a payment link can reopen the payment
+panel. Only a created wallet invoice can be cancelled; the component confirms
+the action, calls `onCancel` with `path.invoice_id`, applies the returned invoice
+and refreshes the current page.
+
+All browser requests start after hydration or a visitor action. Source is
+maintained in `components/orionplace/wallet/StorefrontWallet.tsx`.
+
+### Props
+
+| Prop                                                                                                                                                        | Meaning                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `initialData?: { data: IInvoice[]; rpag: IApiPagination; counts?: { c_wallet: number; c_order: number; c_paid_sub: number; c_writer_earnings: number; }; }` | Server-provided initial data used for the first render and hydration.                                       |
+| `initialCategory?: WalletCategory`                                                                                                                          | Server-provided initial category 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.                                 |
+| `ordersHref?: (orderId: number, locale: string) => string`                                                                                                  | Builds the orders destination from the callback arguments.                                                  |
+| `subscriptionsHref?: (locale: string) => string`                                                                                                            | Builds the subscriptions destination from the callback arguments.                                           |
+| `onLoad: (action: WalletLoadAction) => Promise<InvoicesPage> \| InvoicesPage`                                                                               | Called when the component needs its primary data. The callback payload is shown in its type.                |
+| `onLoadMethods: (action: WalletMethodsAction) => Promise<IPaymentMethod[]> \| IPaymentMethod[]`                                                             | Called when available methods must be loaded. The callback payload is shown in its type.                    |
+| `onCreate: (action: WalletCreateAction) => Promise<IStorefrontPayment> \| IStorefrontPayment`                                                               | Called when the visitor submits a new record. The callback payload is shown in its type.                    |
+| `onCancel: (action: WalletCancelAction) => Promise<IInvoice> \| IInvoice`                                                                                   | Passes an action to cancel the selected invoice, with its ID in `path.invoice_id`. The handler returns the updated invoice, which replaces the previous entry. |
+| `onLoadProfile: (action: WalletProfileAction) => Promise<ProfilePage> \| ProfilePage`                                                                       | Called when the current profile must be refreshed. 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.                   |
+| `onCategoryChange?: (category: WalletCategory) => void`                                                                                                     | Called when the visitor changes the wallet transaction category. The callback payload is shown in its type. |
+
+## Русский
+
+`StorefrontWallet` выводит баланс в выбранной валюте, пополнение кошелька и
+историю платежей покупателя. `initialData` и `initialCategory` позволяют
+показать первую историю на сервере. Без начальных данных после гидратации
+`onLoad` получает метод `invoices_get`, выбранную категорию `wallet`, `orders`
+или `paid_subs` и пагинацию. Необязательные обработчики маршрута получают смену
+категории и страницы.
+
+Действие пополнения сначала вызывает `onLoadMethods`, исключая способы оплаты
+при доставке и с баланса. Затем `WalletTopUpForm` передаёт в `onCreate` точную
+строку суммы, ID способа оплаты и ID валюты. Возвращённая оплата открывается в
+`PaymentPanel`, а история переключается на категорию кошелька с первой страницы,
+где виден новый счёт; `onCategoryChange` сообщает о переключении. Проверка или закрытие этой
+панели обновляет историю и вызывает `onLoadProfile`; кошелёк вошедшего профиля
+из ответа сразу показывается в `WalletBalance`.
+
+Для каждого счёта видны полученное состояние, сумма в выбранной валюте, дата,
+способ и назначение платежа, полезный ID транзакции и комментарий. Платежи по
+заказам и подпискам ведут к соответствующим разделам магазина. Возвраты
+остаются внутри исходного счёта со своим состоянием, суммой, направлением и
+ссылочными данными. Для созданного счёта со ссылкой можно снова открыть оплату.
+Отменить можно только созданный счёт пополнения: компонент запрашивает
+подтверждение, вызывает `onCancel` с `path.invoice_id`, применяет возвращённый
+счёт и обновляет текущую страницу.
+
+Все браузерные запросы начинаются после гидратации или действия посетителя.
+Исходный файл: `components/orionplace/wallet/StorefrontWallet.tsx`.
+
+### Свойства
+
+| Свойство                                                                                                                                                    | Назначение                                                                                               |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `initialData?: { data: IInvoice[]; rpag: IApiPagination; counts?: { c_wallet: number; c_order: number; c_paid_sub: number; c_writer_earnings: number; }; }` | Начальные данные с сервера для первого рендера и гидратации.                                             |
+| `initialCategory?: WalletCategory`                                                                                                                          | Начальное значение категории, полученное на сервере для первого рендера и гидратации.                    |
+| `initialError?: string`                                                                                                                                     | Начальное значение ошибки, полученное на сервере для первого рендера и гидратации.                       |
+| `loadOnMount?: boolean`                                                                                                                                     | Запускает загрузку после гидратации, если серверные данные не переданы.                                  |
+| `ordersHref?: (orderId: number, locale: string) => string`                                                                                                  | Строит адрес ссылки заказов из аргументов обработчика.                                                   |
+| `subscriptionsHref?: (locale: string) => string`                                                                                                            | Строит адрес ссылки подписок из аргументов обработчика.                                                  |
+| `onLoad: (action: WalletLoadAction) => Promise<InvoicesPage> \| InvoicesPage`                                                                               | Вызывается, когда компоненту нужны основные данные. Данные обработчика указаны в его типе.               |
+| `onLoadMethods: (action: WalletMethodsAction) => Promise<IPaymentMethod[]> \| IPaymentMethod[]`                                                             | Вызывается, когда нужно загрузить доступные способы. Данные обработчика указаны в его типе.              |
+| `onCreate: (action: WalletCreateAction) => Promise<IStorefrontPayment> \| IStorefrontPayment`                                                               | Вызывается, когда покупатель отправляет новую запись. Данные обработчика указаны в его типе.             |
+| `onCancel: (action: WalletCancelAction) => Promise<IInvoice> \| IInvoice`                                                                                   | Передаёт действие отмены выбранного счёта с его ID в `path.invoice_id`. Обработчик возвращает обновлённый счёт, которым компонент заменяет прежний. |
+| `onLoadProfile: (action: WalletProfileAction) => Promise<ProfilePage> \| ProfilePage`                                                                       | Вызывается, когда нужно обновить текущий профиль. Данные обработчика указаны в его типе.                 |
+| `onPageChange?: (page: number) => void`                                                                                                                     | Вызывается, когда покупатель открывает другую страницу. Данные обработчика указаны в его типе.           |
+| `onCategoryChange?: (category: WalletCategory) => 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
+
+### How a payment gets its label
+
+`invoice.transaction_direction` — Read each invoice from `invoices_get` → page_data.data. A missing or unrecognized direction leaves the purpose label empty.
+
+| Field or condition | Meaning and application action |
+| --- | --- |
+| Present `parent_type` | Refund of an earlier transaction. This takes precedence over the destination. Its own `status.int` determines whether it is completed. |
+| `to: order` / `to: paid_sub` | Order payment / subscription payment. |
+| `to: deduct` | Balance deduction. |
+| `to: wallet`, `from: promocode_benefit` or `domain_benefit` | Bonus credited to the balance. |
+| Other `to: wallet` | Balance top-up. |
+
+### Links, amounts and confirmation
+
+`invoice` — The transaction label, related record and completion state answer different questions.
+
+| Field or condition | Meaning and application action |
+| --- | --- |
+| `transaction_type` and relation ID | `order` links an order; `paid_sub` links a purchased subscription. The component takes the first positive numeric ID from `order_id`, `transaction_direction.related_id`, then `transaction_direction.parent_related_id`. |
+| Object-valued `parent_related_id` | A refunded wallet payment can identify an account with `id`, `is_staff` and `is_admin`. This object supplies no order/subscription link. Missing usable IDs also leave the relation unlinked. |
+| `amount[currencyId].transform_value` | Display the amount in the selected currency, retaining its sign. Nested `refunds[]` each carry their own amount, destination and status. |
+| `refunds[].status.int` | A refund row records a refund operation. Only `EInvoiceStatus.COMPLETED` confirms completion; `to_balance` identifies balance versus the original payment method. |
+| Status check or close | The supplied wallet reloads `invoices_get` and `profile_get`, then uses the current profile’s `wallet` for the balance. The refreshed status confirms payment; opening or closing `PaymentPanel` alone cannot confirm it. |
+
+### Русский
+
+### Как определяется назначение платежа
+
+`invoice.transaction_direction` — Платежи берутся из `invoices_get` → page_data.data. При отсутствии или неизвестном направлении назначение остаётся пустым.
+
+| Поле или условие | Значение и действие приложения |
+| --- | --- |
+| Есть `parent_type` | Возврат по более ранней операции. Этот признак имеет приоритет над получателем. Завершение определяется собственным `status.int` возврата. |
+| `to: order` / `to: paid_sub` | Оплата заказа / оплата подписки. |
+| `to: deduct` | Списание с баланса. |
+| `to: wallet`, `from: promocode_benefit` или `domain_benefit` | Бонус, зачисленный на баланс. |
+| Другой `to: wallet` | Пополнение баланса. |
+
+### Ссылки, суммы и подтверждение
+
+`invoice` — Назначение платежа, связанная запись и завершение операции определяются отдельными полями.
+
+| Поле или условие | Значение и действие приложения |
+| --- | --- |
+| `transaction_type` и ID связи | `order` открывает заказ, `paid_sub` — купленную подписку. Компонент берёт первый положительный числовой ID из `order_id`, `transaction_direction.related_id`, затем `transaction_direction.parent_related_id`. |
+| Объект в `parent_related_id` | При возврате платежа баланса здесь может быть аккаунт с `id`, `is_staff`, `is_admin`. Объект не даёт ссылки на заказ/подписку. Если подходящего ID нет, ссылка также не выводится. |
+| `amount[currencyId].transform_value` | Сумма выводится в выбранной валюте с сохранением знака. У каждого вложенного `refunds[]` свои сумма, направление и состояние. |
+| `refunds[].status.int` | Позиция возврата описывает операцию возврата. Завершение подтверждает только `EInvoiceStatus.COMPLETED`; `to_balance` указывает возврат на баланс или исходный способ оплаты. |
+| Проверка состояния или закрытие | Готовый кошелёк загружает `invoices_get` и `profile_get`, затем берёт баланс из `wallet` текущего профиля. Оплату подтверждает полученное состояние; открытие или закрытие `PaymentPanel` само по себе её не подтверждает. |
+
+[English guide](https://orionmarket.place/en/sandbox/components/react/wallet) · [Русский](https://orionmarket.place/ru/sandbox/components/react/wallet)