orionplace-react 0.1.0 → 0.2.1

package/templates/components/orionplace/subscriptions/SubscriptionRenewalDialog.tsx

@@ -0,0 +1,253 @@
+'use client';
+
+import '@/components/orionplace/shared/dialogs.css';
+
+import {
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+  type FormEvent,
+  type MouseEvent,
+} from 'react';
+import { useOrionplaceSelections } from '@/providers/OrionplaceProvider';
+import { useOrionplaceDialog } from '@/hooks/useOrionplaceDialog';
+import type { ISubscribeTariff } from '@/interfaces/orionplace/subscribeTariff/ISubscribeTariff';
+import type {
+  ICustomerSubscription,
+  ISubscriptionRenewalSettingRequest,
+} from '@/interfaces/orionplace/subscribes/ISubscriptionApi';
+import {
+  subscriptionManageLabels,
+  subscriptionDays,
+} from '@/lib/orionplace/subscriptionManageLabels';
+import {
+  renewalTotalAmount,
+  subscriptionPeriodChoices,
+} from '@/lib/orionplace/subscriptionPlans';
+import { tariffMoney } from '@/lib/orionplace/tariffs';
+import styles from './SubscriptionDialog.module.css';
+
+export interface SubscriptionRenewalDialogProps {
+  subscription?: ICustomerSubscription;
+  plan?: ISubscribeTariff;
+  pending?: boolean;
+  error?: string;
+  modal?: boolean;
+  onSubmit?: (request: ISubscriptionRenewalSettingRequest) => void;
+  onClose?: () => void;
+}
+
+export function SubscriptionRenewalDialog({
+  subscription,
+  plan,
+  pending = false,
+  error = '',
+  modal = true,
+  onSubmit,
+  onClose,
+}: SubscriptionRenewalDialogProps) {
+  const locale = useOrionplaceSelections((state) => state.localeCode);
+  const currencyId = useOrionplaceSelections((state) => state.currencyId);
+  const currency = useOrionplaceSelections(
+    (state) => state.init?.currencies[state.currencyId],
+  );
+  const copy = subscriptionManageLabels(locale);
+  const id = useId();
+  const { dialog, initialFocus } = useOrionplaceDialog(subscription?.id, modal);
+  const choices = useMemo(
+    () =>
+      subscriptionPeriodChoices(plan, currencyId).map((choice) => ({
+        ...choice,
+        length: subscriptionDays(choice.days, locale),
+        price: tariffMoney(choice.amount, locale, currency),
+      })),
+    [plan, currencyId, locale, currency],
+  );
+  const choiceKey = choices.map((choice) => choice.id).join(',');
+  const renewal = subscription?.renew_period ?? null;
+  const [selected, setSelected] = useState(() => {
+    const matching = choices.find((choice) => choice.days === renewal?.days);
+    return matching ? String(matching.id) : '';
+  });
+  const chosen = choices.find((choice) => String(choice.id) === selected);
+  const unchanged = !chosen && !renewal;
+  const current = renewal
+    ? copy.renewalCurrentOn
+        .replace('{days}', subscriptionDays(renewal.days, locale))
+        .replace(
+          '{price}',
+          tariffMoney(
+            renewalTotalAmount(renewal, currencyId),
+            locale,
+            currency,
+          ),
+        )
+    : copy.renewalCurrentOff;
+  const effect = chosen
+    ? copy.renewalEffectOn
+        .replace('{price}', chosen.price)
+        .replace('{days}', chosen.length)
+    : copy.renewalEffectOff;
+
+  useEffect(() => {
+    const matching = choices.find((choice) => choice.days === renewal?.days);
+    setSelected(matching ? String(matching.id) : '');
+  }, [subscription?.id, renewal?.days, choiceKey]);
+
+  function close() {
+    if (!pending) {
+      onClose?.();
+    }
+  }
+
+  function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!pending && !unchanged && subscription) {
+      onSubmit?.({
+        existed_subscription: subscription.id,
+        ...(chosen ? { renew_period: chosen.id } : {}),
+      });
+    }
+  }
+
+  function backdrop(event: MouseEvent<HTMLDialogElement>) {
+    const bounds = dialog.current?.getBoundingClientRect();
+    if (
+      modal &&
+      event.target === dialog.current &&
+      bounds &&
+      (event.clientX < bounds.left ||
+        event.clientX > bounds.right ||
+        event.clientY < bounds.top ||
+        event.clientY > bounds.bottom)
+    ) {
+      close();
+    }
+  }
+
+  if (!subscription) {
+    return null;
+  }
+
+  return (
+    <dialog
+      data-stable-modal="form"
+      ref={dialog}
+      className={`${styles.dialog} ${modal ? '' : styles.inline}`.trim()}
+      aria-labelledby={`${id}-title`}
+      aria-describedby={`${id}-effect`}
+      aria-busy={pending}
+      data-feature-part="SubscriptionRenewalDialog"
+      data-subscription-renewal-dialog
+      onCancel={(event) => {
+        event.preventDefault();
+        close();
+      }}
+      onKeyDown={(event) => {
+        // Escape belongs to this window, not to the page behind it.
+        if (event.key === 'Escape') {
+          event.stopPropagation();
+        }
+      }}
+      onClick={backdrop}
+    >
+      <form
+        className={styles.form}
+        onSubmit={submit}
+      >
+        <header className={styles.header}>
+          <div>
+            <p className={styles.eyebrow}>{copy.manage}</p>
+            <h2
+              id={`${id}-title`}
+              className={styles.title}
+            >
+              {copy.renewalTitle}
+            </h2>
+          </div>
+          <button
+            ref={initialFocus}
+            type="button"
+            className={styles.close}
+            disabled={pending}
+            aria-label={copy.close}
+            onClick={close}
+          >
+            ×
+          </button>
+        </header>
+        <p className={styles.notice}>{current}</p>
+        <fieldset className={styles.fieldset}>
+          <legend>{copy.renewalHint}</legend>
+          <label className={`${styles.choice} ${styles.choiceOff}`}>
+            <input
+              type="radio"
+              name="renew_period"
+              value=""
+              checked={!selected}
+              disabled={pending}
+              onChange={() => setSelected('')}
+            />
+            <span>
+              <span>{copy.renewalOff}</span>
+              <span className={styles.hint}>{copy.renewalOffHint}</span>
+            </span>
+          </label>
+          {choices.map((choice) => (
+            <label
+              key={choice.id}
+              className={styles.choice}
+            >
+              <span>
+                <input
+                  type="radio"
+                  name="renew_period"
+                  value={choice.id}
+                  checked={selected === String(choice.id)}
+                  disabled={pending}
+                  onChange={() => setSelected(String(choice.id))}
+                />
+                <span>{choice.length}</span>
+              </span>
+              <span>{choice.price}</span>
+            </label>
+          ))}
+        </fieldset>
+        <p
+          id={`${id}-effect`}
+          className={styles.description}
+        >
+          {effect}
+        </p>
+        {error ? (
+          <p
+            role="alert"
+            className={styles.error}
+          >
+            {error}
+          </p>
+        ) : null}
+        <div className={styles.actions}>
+          <button
+            type="button"
+            className={styles.secondary}
+            disabled={pending}
+            onClick={close}
+          >
+            {copy.cancel}
+          </button>
+          <button
+            type="submit"
+            className={styles.primary}
+            disabled={pending || unchanged}
+            title={unchanged ? copy.renewalNoChange : undefined}
+          >
+            {pending ? <span className={styles.spinner} aria-hidden="true" /> : null}
+            {pending ? copy.renewalPending : copy.renewalSubmit}
+          </button>
+        </div>
+      </form>
+    </dialog>
+  );
+}

package/templates/components/orionplace/support/StorefrontSupport.README.md

@@ -0,0 +1,157 @@
+# StorefrontSupport · React
+
+## English
+
+`StorefrontSupport` is the customer support route composition. `initialData`,
+`initialSelected`, `initialReplies`, `initialSubscriptions` and
+`initialSubject` can render the first screen on the server. When list data is
+absent and `loadOnMount` is enabled, the component calls `onLoadTickets` with
+`customer_tickets_get`, the selected open or closed status and pagination. A
+`ticketId` additionally loads that conversation by ID and its complete replies.
+`status` and `page` choose the list tab and page.
+
+Opening a list row loads all replies through
+`customer_tickets_reply_getall`. A return conversation is first re-read by ID
+when its list item does not contain the return order. Unread count becomes zero
+after the replies arrive. Subscription data is loaded only when a listed,
+selected or new conversation needs it. A new item or option subject uses
+`onLoadOrder` and `context.orderId`; failure to load this visual subject does
+not block sending the conversation. The line's `refund_window` reaches
+`TicketMessageForm` as `refundWindow`: inside the regular return period the
+customer may mark the item as defective, after it the request is marked as a
+defect and says why; a marked request adds `is_defect: true` to `data`. The
+backend allows one open request per line and refuses a second one with “A
+request for this item is already open.”; the form shows the backend's message
+as returned and keeps the text and files.
+
+New conversations and replies are passed to `onSubmit` as `FormData`: JSON is
+stored in `data`, and every image uses a repeated `ticket_images` field. The
+endpoint and ID field match `context.kind`; replies use the selected ticket ID.
+After success, the component refreshes the open list, selected ticket and
+complete replies before enabling another write. If a required refresh fails,
+it preserves the visible result, blocks writes and offers an explicit retry.
+Close, delete and rating actions use `onMutate` with `path.ticket_id`, then
+refresh the affected data.
+
+The place on the page lives in the URL as `?status&page&ticket`. Every
+tab, page, opened or closed conversation, send and delete calls `onNavigate`
+with `{ status, page, ticket? }`; `SupportPage` writes it with
+`ticketLocationQuery()` and `window.history`, so Next.js does not render the
+server page again, and a reload or the browser's Back button returns to the
+same place. When the props change (Back), the component reads the list only if
+the tab or page differs and the conversation only if another one is asked for.
+Its own navigation already matches its state and sends no request.
+
+An open conversation whose `reply_wait` is set (no support reply yet, or the
+store's reply delay after the customer's last message) locks the message form
+with the `ticketReplyWaitText()` hint. A `delay` wait unlocks by itself after
+`reply_wait.seconds`; the refresh button reads the ticket again, so a support
+reply unlocks the form.
+
+Protected images use `onLoadImage`. All browser work starts in effects or visitor actions, so
+server rendering with initial data does not access browser globals or issue a
+request. Source is maintained in
+`components/orionplace/support/StorefrontSupport.tsx`.
+
+### Props
+
+| Prop                                                                                                                                         | Meaning                                                                                                        |
+| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `ticketId?: number`                                                                                                                          | Open conversation from the page URL (`?ticket`); a change opens that conversation.                             |
+| `status?: ECustomerTicketStatus`                                                                                                             | List tab from the page URL (`?status`); `ECustomerTicketStatus.OPEN` by default.                               |
+| `page?: number`                                                                                                                              | List page from the page URL (`?page`); 1 by default.                                                           |
+| `context?: TicketSubjectContext`                                                                                                             | Optional order, item or subscription context for a new support request.                                        |
+| `initialData?: { data: ICustomerTicket[]; rpag: IApiPagination; counts?: { c_opened: number; c_closed: number; }; }`                         | Server-provided initial data used for the first render and hydration.                                          |
+| `initialSelected?: ICustomerTicket`                                                                                                          | Server-provided initial selected used for the first render and hydration.                                      |
+| `initialReplies?: ICustomerTicketReply[]`                                                                                                    | Server-provided initial replies used for the first render and hydration.                                       |
+| `initialSubscriptions?: { data: ICustomerSubscription[]; subscriptions: IPublicSubscription[]; tariffs: ISubscribeTariff[]; }`               | Server-provided initial subscriptions used for the first render and hydration.                                 |
+| `initialSubject?: StorefrontSupportSubject`                                                                                                  | Server-provided initial subject 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.                                    |
+| `onLoadTickets: (action: SupportTicketsAction) => Promise<TicketsPage> \| TicketsPage`                                                       | Called when the support-ticket list must be loaded. The callback payload is shown in its type.                 |
+| `onLoadReplies: (action: SupportRepliesAction) => Promise<ICustomerTicketReply[]> \| ICustomerTicketReply[]`                                 | Called when the complete conversation or reply page must be loaded. The callback payload is shown in its type. |
+| `onLoadSubscriptions?: (action: SupportSubscriptionsAction) => Promise<SubscriptionsPage> \| SubscriptionsPage`                              | Called when the customer subscriptions must be refreshed. The callback payload is shown in its type.           |
+| `onLoadOrder?: (action: SupportOrderAction) => Promise<OrdersPage> \| OrdersPage`                                                            | Called when the related order must be loaded. The callback payload is shown in its type.                       |
+| `onLoadImage: (action: TicketImageLoadAction) => Promise<Blob> \| Blob`                                                                      | Called when a protected image must be loaded. The callback payload is shown in its type.                       |
+| `onSubmit: (action: SupportSubmitAction) => Promise<ICustomerTicket \| ICustomerTicketReply[]> \| ICustomerTicket \| ICustomerTicketReply[]` | Called when the visitor submits the confirmed form values. The callback payload is shown in its type.          |
+| `onMutate: (action: SupportMutationAction) => Promise<void> \| void`                                                                         | Called when the visitor confirms a support-ticket change. The callback payload is shown in its type.           |
+| `onNavigate?: (location: TicketLocation, replace: boolean) => void`                                                                          | Called with `{ status, page, ticket? }` on each move; `replace` is `true` after a send or delete.              |
+
+## Русский
+
+`StorefrontSupport` — композиция страницы поддержки покупателя. Параметры
+`initialData`, `initialSelected`, `initialReplies`, `initialSubscriptions` и
+`initialSubject` позволяют вывести первый экран на сервере. Если списка нет и
+включён `loadOnMount`, компонент вызывает `onLoadTickets` с методом
+`customer_tickets_get`, выбранным открытым или закрытым состоянием и пагинацией.
+При наличии `ticketId` отдельно загружаются обращение по ID и все его сообщения.
+`status` и `page` выбирают вкладку и страницу списка.
+
+При открытии строки все сообщения загружаются через
+`customer_tickets_reply_getall`. Обращение по возврату сначала повторно читается
+по ID, если в элементе списка нет заказа возврата. После получения сообщений
+счётчик непрочитанных становится нулём. Подписки загружаются только тогда, когда
+они нужны строке списка, открытому обращению или новому обращению. Для нового
+обращения по товару или дополнению `onLoadOrder` читает заказ из
+`context.orderId`; ошибка этой вспомогательной карточки не блокирует отправку.
+`refund_window` позиции передаётся в `TicketMessageForm` как `refundWindow`:
+пока идёт срок возврата, покупатель может отметить брак, после него заявка
+отмечена как брак и форма объясняет почему; отмеченная заявка добавляет
+`is_defect: true` в `data`. Бэкенд допускает одну открытую заявку на позицию
+и отклоняет вторую сообщением «A request for this item is already open.»;
+форма показывает сообщение бэкенда как есть и сохраняет текст и файлы.
+
+Новые обращения и ответы передаются в `onSubmit` как `FormData`: JSON находится
+в поле `data`, каждое изображение — в повторяющемся поле `ticket_images`. Метод
+и поле ID соответствуют `context.kind`, а ответ содержит ID открытого обращения.
+После успеха компонент обновляет открытый список, выбранное обращение и все
+сообщения и только затем разрешает следующую запись. Если обязательное
+обновление не удалось, видимый результат сохраняется, запись блокируется и
+появляется явное действие повтора. Закрытие, удаление и оценка вызывают
+`onMutate` с `path.ticket_id`, затем обновляют затронутые данные.
+
+Место на странице хранится в адресе как `?status&page&ticket`. Каждая смена
+вкладки или страницы, открытие или закрытие обращения, отправка и удаление
+вызывают `onNavigate` с `{ status, page, ticket? }`; `SupportPage` записывает
+его через `ticketLocationQuery()` и `window.history`, поэтому Next.js не
+отрисовывает серверную страницу заново, а перезагрузка и кнопка «Назад»
+браузера возвращают на то же место. При изменении свойств (кнопка «Назад»)
+компонент читает список, только если вкладка или страница отличаются, и
+обращение, только если запрошено другое. Собственные переходы уже совпадают с
+состоянием и запросов не отправляют.
+
+Если у открытого обращения задан `reply_wait` (поддержка ещё не ответила или
+не прошла задержка магазина после последнего сообщения покупателя), форма
+сообщения блокируется с подсказкой `ticketReplyWaitText()`. Ожидание `delay`
+снимается само через `reply_wait.seconds`; кнопка обновления заново читает
+обращение, поэтому ответ поддержки разблокирует форму.
+
+Защищённые изображения загружаются через `onLoadImage`. Работа с браузером
+начинается только в эффектах или после действия посетителя, поэтому серверный
+рендеринг с начальными данными не обращается к браузерным объектам и не
+выполняет запросы. Исходный файл:
+`components/orionplace/support/StorefrontSupport.tsx`.
+
+### Свойства
+
+| Свойство                                                                                                                                     | Назначение                                                                                                        |
+| -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `ticketId?: number`                                                                                                                          | Открытое обращение из адреса страницы (`?ticket`); при изменении открывается это обращение.                       |
+| `status?: ECustomerTicketStatus`                                                                                                             | Вкладка списка из адреса (`?status`); по умолчанию `ECustomerTicketStatus.OPEN`.                                  |
+| `page?: number`                                                                                                                              | Страница списка из адреса (`?page`); по умолчанию 1.                                                              |
+| `context?: TicketSubjectContext`                                                                                                             | Необязательный заказ, товар или подписка для нового обращения в поддержку.                                        |
+| `initialData?: { data: ICustomerTicket[]; rpag: IApiPagination; counts?: { c_opened: number; c_closed: number; }; }`                         | Начальные данные с сервера для первого рендера и гидратации.                                                      |
+| `initialSelected?: ICustomerTicket`                                                                                                          | Начальное значение выбранного значения, полученное на сервере для первого рендера и гидратации.                   |
+| `initialReplies?: ICustomerTicketReply[]`                                                                                                    | Начальное значение ответов, полученное на сервере для первого рендера и гидратации.                               |
+| `initialSubscriptions?: { data: ICustomerSubscription[]; subscriptions: IPublicSubscription[]; tariffs: ISubscribeTariff[]; }`               | Начальное значение подписок, полученное на сервере для первого рендера и гидратации.                              |
+| `initialSubject?: StorefrontSupportSubject`                                                                                                  | Начальное значение предмета обращения, полученное на сервере для первого рендера и гидратации.                    |
+| `initialError?: string`                                                                                                                      | Начальное значение ошибки, полученное на сервере для первого рендера и гидратации.                                |
+| `loadOnMount?: boolean`                                                                                                                      | Запускает загрузку после гидратации, если серверные данные не переданы.                                           |
+| `onLoadTickets: (action: SupportTicketsAction) => Promise<TicketsPage> \| TicketsPage`                                                       | Вызывается, когда нужно загрузить список обращений. Данные обработчика указаны в его типе.                        |
+| `onLoadReplies: (action: SupportRepliesAction) => Promise<ICustomerTicketReply[]> \| ICustomerTicketReply[]`                                 | Вызывается, когда нужно загрузить переписку или страницу ответов. Данные обработчика указаны в его типе.          |
+| `onLoadSubscriptions?: (action: SupportSubscriptionsAction) => Promise<SubscriptionsPage> \| SubscriptionsPage`                              | Вызывается, когда нужно обновить подписки покупателя. Данные обработчика указаны в его типе.                      |
+| `onLoadOrder?: (action: SupportOrderAction) => Promise<OrdersPage> \| OrdersPage`                                                            | Вызывается, когда нужно загрузить связанный заказ. Данные обработчика указаны в его типе.                         |
+| `onLoadImage: (action: TicketImageLoadAction) => Promise<Blob> \| Blob`                                                                      | Вызывается, когда нужно загрузить защищённое изображение. Данные обработчика указаны в его типе.                  |
+| `onSubmit: (action: SupportSubmitAction) => Promise<ICustomerTicket \| ICustomerTicketReply[]> \| ICustomerTicket \| ICustomerTicketReply[]` | Вызывается, когда покупатель отправляет подтверждённые значения формы. Данные обработчика указаны в его типе.     |
+| `onMutate: (action: SupportMutationAction) => Promise<void> \| void`                                                                         | Вызывается, когда покупатель подтверждает изменение обращения. Данные обработчика указаны в его типе.             |
+| `onNavigate?: (location: TicketLocation, replace: boolean) => void`                                                                          | Вызывается с `{ status, page, ticket? }` при каждом переходе; `replace` равен `true` после отправки или удаления. |