orionplace-react 0.1.0 → 0.2.1

package/templates/lib/orionplace/ticketLabels.ts

@@ -0,0 +1,335 @@
+import {
+  ECustomerTicketSolution,
+  ECustomerTicketStatus,
+  ECustomerTicketType,
+  EOrderRefundShipmentStatus,
+} from '@/interfaces/orionplace/tickets/ICustomerTicketApi';
+import type { ICustomerTicketReplyWait } from '@/interfaces/orionplace/tickets/ICustomerTicketApi';
+
+const en = {
+  title: 'Support',
+  new: 'New conversation',
+  newAction: 'New',
+  newHint: 'New conversation',
+  ticket: 'Conversation',
+  open: 'Open',
+  closed: 'Closed',
+  statusOpen: 'Open',
+  statusClosed: 'Closed',
+  empty: 'No conversations in this category.',
+  message: 'Message',
+  images: 'Images',
+  attach: 'Attach',
+  choose: 'Choose a conversation or start a new one.',
+  back: 'Conversations',
+  backHint: 'All conversations',
+  send: 'Send',
+  create: 'Create',
+  close: 'Close',
+  closeHint: 'Close conversation',
+  closeQuestion:
+    'Close this conversation? You will no longer be able to reply here.',
+  delete: 'Delete',
+  deleteHint: 'Delete conversation',
+  deleteQuestion: 'Delete this conversation and its message?',
+  rating: 'Rate the support you received',
+  unrated: 'No rating',
+  rated: 'Your rating',
+  image: 'Attached image',
+  imageError: 'Could not load this image.',
+  removeImage: 'Remove image',
+  tooMany: 'Choose up to five images for one message.',
+  product: 'About an item in your order',
+  option: 'About an option in your order',
+  subscription: 'About your subscription',
+  common: 'Describe how we can help.',
+  unread: 'Unread messages',
+  sent: 'Sent',
+  order: 'View order',
+  refreshRequired: 'Refresh the conversation before sending another message.',
+  waitSupport: 'Wait for the support reply. You can add details after it.',
+  waitDelay:
+    'Wait for the support reply. You can send another message a few minutes after your previous one.',
+  draftLost: 'The message was saved. Refresh to see the conversation.',
+  typeCommon: 'General question',
+  typeOrder: 'Order item',
+  typeSeller: 'Seller question',
+  typeSubscription: 'Subscription',
+  refundCanceled: 'Return canceled',
+  refundCreated: 'Waiting to be sent back',
+  refundSent: 'Return sent',
+  refundReceived: 'Received by the store',
+  refundDone: 'Refund approved',
+  refundProblem: 'Refund refused',
+  refundHints: {
+    canceled: 'This return has been canceled, so no refund follows it.',
+    created: 'Send the items below back with the carrier of this return.',
+    sent: 'The return is on its way to the store.',
+    received: 'The store has received the return.',
+    done: 'The refund for the returned items has been approved.',
+    problem:
+      'The store refused the items it received back, so that money is not paid.',
+  },
+  refund: 'Return',
+  refundCarrier: 'Carrier',
+  refundTrack: 'Return tracking number',
+  refundAmount: 'Refund amount',
+  refundCarrierStatus: 'Carrier status',
+  refundItems: 'Items in this return',
+  subject: 'This conversation is about',
+  subscriptionSubject: 'This conversation is about the subscription',
+  itemUnknown: 'Item no longer available',
+  itemOption: 'Option',
+  itemQuantity: 'Quantity',
+  itemPrice: 'Paid',
+  itemPicture: 'Picture',
+  refundCounts: {
+    awaiting: 'To send back',
+    received: 'Received back',
+    approved: 'Approved for refund',
+    defect: 'Of them defective',
+  },
+  defect: 'Defect',
+  defectOptional: 'The item is defective',
+  defectOnly:
+    'The regular return period is over; a return is possible for a defect only.',
+  decision: 'Decision',
+  decisionPending: 'Under review',
+  decisionApproved: 'Approved',
+  decisionDeclined: 'Declined',
+};
+
+const ru: typeof en = {
+  title: 'Поддержка',
+  new: 'Новое обращение',
+  newAction: 'Создать',
+  newHint: 'Создать обращение',
+  ticket: 'Обращение',
+  open: 'Открытые',
+  closed: 'Закрытые',
+  statusOpen: 'Открыто',
+  statusClosed: 'Закрыто',
+  empty: 'В этой категории нет обращений.',
+  message: 'Сообщение',
+  images: 'Изображения',
+  attach: 'Прикрепить',
+  choose: 'Выберите обращение или создайте новое.',
+  back: 'Обращения',
+  backHint: 'Все обращения',
+  send: 'Отправить',
+  create: 'Создать',
+  close: 'Закрыть',
+  closeHint: 'Закрыть обращение',
+  closeQuestion:
+    'Закрыть это обращение? Отправлять в него ответы больше не получится.',
+  delete: 'Удалить',
+  deleteHint: 'Удалить обращение',
+  deleteQuestion: 'Удалить это обращение и сообщение в нём?',
+  rating: 'Оцените помощь поддержки',
+  unrated: 'Без оценки',
+  rated: 'Ваша оценка',
+  image: 'Прикреплённое изображение',
+  imageError: 'Не удалось загрузить изображение.',
+  removeImage: 'Убрать изображение',
+  tooMany: 'К одному сообщению можно прикрепить до пяти изображений.',
+  product: 'По товару из заказа',
+  option: 'По дополнению к товару из заказа',
+  subscription: 'По вашей подписке',
+  common: 'Опишите, какая помощь нужна.',
+  unread: 'Непрочитанные сообщения',
+  sent: 'Отправлено',
+  order: 'Посмотреть заказ',
+  refreshRequired: 'Обновите обращение перед отправкой следующего сообщения.',
+  waitSupport: 'Дождитесь ответа поддержки. Дополнить обращение можно будет после него.',
+  waitDelay:
+    'Дождитесь ответа поддержки. Следующее сообщение можно отправить через несколько минут после предыдущего.',
+  draftLost: 'Сообщение сохранено. Обновите переписку, чтобы увидеть его.',
+  typeCommon: 'Общий вопрос',
+  typeOrder: 'Товар из заказа',
+  typeSeller: 'Вопрос продавца',
+  typeSubscription: 'Подписка',
+  refundCanceled: 'Возврат отменён',
+  refundCreated: 'Ожидает отправки обратно',
+  refundSent: 'Возврат отправлен',
+  refundReceived: 'Получен магазином',
+  refundDone: 'Выплата возврата одобрена',
+  refundProblem: 'В возврате отказано',
+  refundHints: {
+    canceled: 'Этот возврат отменён, выплаты по нему не будет.',
+    created: 'Отправьте товары ниже обратно перевозчиком этого возврата.',
+    sent: 'Возврат в пути в магазин.',
+    received: 'Магазин получил возврат.',
+    done: 'Выплата за возвращённые товары одобрена.',
+    problem:
+      'Магазин отказал в возврате полученных товаров, эти деньги не будут выплачены.',
+  },
+  refund: 'Возврат',
+  refundCarrier: 'Перевозчик',
+  refundTrack: 'Трек-номер возврата',
+  refundAmount: 'Сумма возврата',
+  refundCarrierStatus: 'Статус перевозчика',
+  refundItems: 'Товары в этом возврате',
+  subject: 'Обращение по этому товару',
+  subscriptionSubject: 'Обращение по этой подписке',
+  itemUnknown: 'Товар больше не доступен',
+  itemOption: 'Дополнение',
+  itemQuantity: 'Количество',
+  itemPrice: 'Оплачено',
+  itemPicture: 'Фото',
+  refundCounts: {
+    awaiting: 'К отправке обратно',
+    received: 'Получено обратно',
+    approved: 'Одобрено к возврату',
+    defect: 'Из них с браком',
+  },
+  defect: 'Брак',
+  defectOptional: 'Товар с браком',
+  defectOnly:
+    'Срок обычного возврата истёк; возврат возможен только по браку.',
+  decision: 'Решение',
+  decisionPending: 'На рассмотрении',
+  decisionApproved: 'Одобрено',
+  decisionDeclined: 'Отклонено',
+};
+
+export type TicketStatusIcon = 'lock' | 'unlock';
+
+export interface TicketStatusView {
+  icon?: TicketStatusIcon;
+  text: string;
+}
+
+export function ticketLabels(locale: string) {
+  return locale.toLowerCase().startsWith('ru') ? ru : en;
+}
+
+// The backend status text is not translated, so known statuses use the
+// storefront labels; an unknown value keeps the returned text without an icon.
+export function ticketStatusView(
+  status: { int: number; text: string },
+  labels: typeof en,
+): TicketStatusView {
+  if (status.int === ECustomerTicketStatus.OPEN) {
+    return { icon: 'unlock', text: labels.statusOpen };
+  }
+  if (status.int === ECustomerTicketStatus.CLOSED) {
+    return { icon: 'lock', text: labels.statusClosed };
+  }
+  return { text: status.text };
+}
+
+export function ticketTypeText(
+  type: { int: number; text: string },
+  labels: typeof en,
+) {
+  const known = {
+    [ECustomerTicketType.COMMON]: labels.typeCommon,
+    [ECustomerTicketType.ORDER]: labels.typeOrder,
+    [ECustomerTicketType.SELLER]: labels.typeSeller,
+    [ECustomerTicketType.SUBSCRIPTION]: labels.typeSubscription,
+  } as Record<number, string>;
+
+  return known[type.int] ?? type.text;
+}
+
+export function refundShipmentText(
+  status: { int: number; text: string },
+  labels: typeof en,
+) {
+  const known = {
+    [EOrderRefundShipmentStatus.CANCELED]: labels.refundCanceled,
+    [EOrderRefundShipmentStatus.CREATED]: labels.refundCreated,
+    [EOrderRefundShipmentStatus.SENT]: labels.refundSent,
+    [EOrderRefundShipmentStatus.RECIEVED]: labels.refundReceived,
+    [EOrderRefundShipmentStatus.DONE]: labels.refundDone,
+    [EOrderRefundShipmentStatus.PROBLEM]: labels.refundProblem,
+  } as Record<number, string>;
+
+  return known[status.int] ?? status.text;
+}
+
+export type RefundShipmentTone = 'neutral' | 'progress' | 'success' | 'danger';
+
+export interface RefundShipmentView {
+  text: string;
+  hint: string;
+  tone: RefundShipmentTone;
+}
+
+// The state of the return shipment decides what the customer does next, so the
+// short hint belongs beside it.
+export function refundShipmentView(
+  status: { int: number; text: string },
+  labels: typeof en,
+): RefundShipmentView {
+  const views = {
+    [EOrderRefundShipmentStatus.CANCELED]: {
+      hint: labels.refundHints.canceled,
+      tone: 'danger',
+    },
+    [EOrderRefundShipmentStatus.CREATED]: {
+      hint: labels.refundHints.created,
+      tone: 'progress',
+    },
+    [EOrderRefundShipmentStatus.SENT]: {
+      hint: labels.refundHints.sent,
+      tone: 'progress',
+    },
+    [EOrderRefundShipmentStatus.RECIEVED]: {
+      hint: labels.refundHints.received,
+      tone: 'progress',
+    },
+    [EOrderRefundShipmentStatus.DONE]: {
+      hint: labels.refundHints.done,
+      tone: 'success',
+    },
+    [EOrderRefundShipmentStatus.PROBLEM]: {
+      hint: labels.refundHints.problem,
+      tone: 'danger',
+    },
+  } as Record<number, { hint: string; tone: RefundShipmentTone }>;
+  const view = views[status.int];
+
+  return {
+    text: refundShipmentText(status, labels),
+    hint: view?.hint ?? '',
+    tone: view?.tone ?? 'neutral',
+  };
+}
+
+export function ticketSolutionText(
+  solution: { int: number; text: string },
+  labels: typeof en,
+) {
+  const known = {
+    [ECustomerTicketSolution.SOLUTION_NO_DECISION]: labels.decisionPending,
+    [ECustomerTicketSolution.SOLUTION_APROOVED]: labels.decisionApproved,
+    [ECustomerTicketSolution.SOLUTION_DENIED]: labels.decisionDeclined,
+  } as Record<number, string>;
+
+  return known[solution.int] ?? solution.text;
+}
+
+export function ticketSolutionTone(solution: { int: number }) {
+  if (solution.int === ECustomerTicketSolution.SOLUTION_APROOVED) {
+    return 'success';
+  }
+  if (solution.int === ECustomerTicketSolution.SOLUTION_DENIED) {
+    return 'danger';
+  }
+
+  return 'neutral';
+}
+
+// The hint shown instead of the message form while the backend would reject
+// a new customer message (`reply_wait` of the ticket); empty when allowed.
+export function ticketReplyWaitText(
+  wait: ICustomerTicketReplyWait | null | undefined,
+  labels: typeof en,
+) {
+  if (!wait) {
+    return '';
+  }
+
+  return wait.reason === 'delay' ? labels.waitDelay : labels.waitSupport;
+}

package/templates/lib/orionplace/ticketLocation.ts

@@ -0,0 +1,79 @@
+import { ECustomerTicketStatus } from '@/interfaces/orionplace/tickets/ICustomerTicketApi';
+
+// Where the support page is: the list tab, the list page and the open
+// conversation. The page keeps it in the URL as `?status&page&ticket`, so a
+// reload and the browser's Back button return to the same place.
+export interface TicketLocation {
+  status: ECustomerTicketStatus;
+  page: number;
+  ticket?: number;
+}
+
+type QueryValue = string | null | undefined | readonly (string | null)[];
+
+const locationKeys = ['status', 'page', 'ticket'];
+// A new conversation about an order item, option or subscription.
+const subjectKeys  = ['item', 'option', 'subscription', 'order'];
+
+function first(value: QueryValue) {
+  return Array.isArray(value) ? value[0] : (value as string | null | undefined);
+}
+
+export function positiveQueryId(value: QueryValue) {
+  const id = Number(first(value));
+
+  return Number.isSafeInteger(id) && id > 0 ? id : undefined;
+}
+
+// `status` is `ECustomerTicketStatus`; any other value means Open.
+export function ticketLocationFromQuery(
+  query: Record<string, QueryValue>,
+): TicketLocation {
+  const closed = first(query.status) === String(ECustomerTicketStatus.CLOSED);
+
+  return {
+    status: closed ? ECustomerTicketStatus.CLOSED : ECustomerTicketStatus.OPEN,
+    page: positiveQueryId(query.page) ?? 1,
+    ticket: positiveQueryId(query.ticket),
+  };
+}
+
+export function sameTicketLocation(left: TicketLocation, right: TicketLocation) {
+  return (
+    left.status === right.status &&
+    left.page === right.page &&
+    left.ticket === right.ticket
+  );
+}
+
+// The query of `next`: other parameters such as `locale` stay, defaults are
+// left out, and an open conversation drops the new-conversation subject.
+export function ticketLocationQuery(
+  query: Record<string, QueryValue>,
+  next: TicketLocation,
+) {
+  const result: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(query)) {
+    const text = first(value);
+    if (typeof text === 'string' && !locationKeys.includes(key)) {
+      result[key] = text;
+    }
+  }
+  if (next.ticket) {
+    for (const key of subjectKeys) {
+      delete result[key];
+    }
+  }
+  if (next.status !== ECustomerTicketStatus.OPEN) {
+    result.status = String(next.status);
+  }
+  if (next.page > 1) {
+    result.page = String(next.page);
+  }
+  if (next.ticket) {
+    result.ticket = String(next.ticket);
+  }
+
+  return result;
+}

package/templates/lib/orionplace/ticketRequests.ts

@@ -0,0 +1,70 @@
+export type TicketSubjectKind = 'item' | 'option' | 'subscription';
+
+export interface TicketSubjectContext {
+  kind: TicketSubjectKind;
+  id: number;
+  orderId?: number;
+}
+
+export type TicketSubmitEndpoint =
+  | 'customer_tickets_add'
+  | 'customer_tickets_reply'
+  | 'customer_tickets_order_item_add'
+  | 'customer_tickets_order_option_add'
+  | 'customer_tickets_subscription_add';
+
+export interface TicketSubmitTarget {
+  endpoint: TicketSubmitEndpoint;
+  data: Record<string, string | number | boolean>;
+}
+
+// A return request is marked as a defect only when it is one; the backend
+// reads a missing mark as an ordinary return.
+export function ticketSubmitTarget(
+  text: string,
+  ticketId?: number,
+  context?: TicketSubjectContext,
+  isDefect = false,
+): TicketSubmitTarget {
+  const data: Record<string, string | number | boolean> = {
+    ticket_body: text,
+  };
+
+  if (ticketId !== undefined) {
+    return {
+      endpoint: 'customer_tickets_reply',
+      data: { ...data, ticket: ticketId },
+    };
+  }
+  if (!context) {
+    return { endpoint: 'customer_tickets_add', data };
+  }
+
+  const targets           = {
+    item: ['customer_tickets_order_item_add', 'order_dlf_item'],
+    option: ['customer_tickets_order_option_add', 'order_option_item'],
+    subscription: [
+      'customer_tickets_subscription_add',
+      'related_paid_subscription',
+    ],
+  } as const;
+  const [endpoint, field] = targets[context.kind];
+
+  data[field]             = context.id;
+  if (isDefect && context.kind !== 'subscription') {
+    data.is_defect = true;
+  }
+
+  return { endpoint, data };
+}
+
+export function ticketFormData(target: TicketSubmitTarget, files: File[]) {
+  const body = new FormData();
+
+  body.append('data', JSON.stringify(target.data));
+  for (const file of files) {
+    body.append('ticket_images', file, file.name);
+  }
+
+  return body;
+}

package/templates/lib/orionplace/walletTransaction.ts

@@ -0,0 +1,105 @@
+import type {
+  IInvoice,
+  IInvoiceDirection,
+} from '@/interfaces/orionplace/payments/IInvoice';
+
+export type WalletRelationKind = 'order' | 'subscription';
+
+export interface IWalletRelation {
+  kind: WalletRelationKind;
+  id: number;
+}
+
+export type WalletPurpose =
+  | 'topUp'
+  | 'deduction'
+  | 'orderPayment'
+  | 'subscriptionPayment'
+  | 'bonus'
+  | 'refund';
+
+const BONUS_SOURCES = ['promocode_benefit', 'domain_benefit'];
+
+function recordId(value: IInvoiceDirection['parent_related_id']) {
+  return typeof value === 'number' && value > 0 ? value : null;
+}
+
+export function walletRelation(invoice: IInvoice): IWalletRelation | null {
+  const direction = invoice.transaction_direction;
+  const related =
+    recordId(invoice.order_id) ??
+    recordId(direction?.related_id) ??
+    recordId(direction?.parent_related_id);
+
+  if (!related) {
+    return null;
+  }
+  if (invoice.transaction_type === 'order') {
+    return { kind: 'order', id: related };
+  }
+  if (invoice.transaction_type === 'paid_sub') {
+    return { kind: 'subscription', id: related };
+  }
+
+  return null;
+}
+
+export function walletComment(invoice: IInvoice): string | null {
+  const written =
+    typeof invoice.comment === 'string' ? invoice.comment.trim() : '';
+
+  if (!written) {
+    return null;
+  }
+
+  const relation = walletRelation(invoice);
+  if (!relation) {
+    return written;
+  }
+
+  const printed = [invoice.id, relation.id];
+  const numbers = written.match(/\d+/g) ?? [];
+  const repeats =
+    numbers.length > 0 &&
+    numbers.every((number) => printed.includes(Number(number)));
+
+  return repeats ? null : written;
+}
+
+export function walletPurpose(invoice: IInvoice): WalletPurpose | null {
+  const direction = invoice.transaction_direction;
+
+  if (!direction) {
+    return null;
+  }
+  if (direction.parent_type) {
+    return 'refund';
+  }
+  if (direction.to === 'order') {
+    return 'orderPayment';
+  }
+  if (direction.to === 'paid_sub') {
+    return 'subscriptionPayment';
+  }
+  if (direction.to === 'deduct') {
+    return 'deduction';
+  }
+  if (direction.to === 'wallet') {
+    return BONUS_SOURCES.includes(direction.from) ? 'bonus' : 'topUp';
+  }
+
+  return null;
+}
+
+/**
+ * A payment the customer made, or a deduction: the history shows it as money
+ * going out (−$38.22) in the text colour, while top-ups, bonuses and refunds
+ * read green.
+ */
+export function walletOutgoing(purpose: WalletPurpose | null): boolean {
+  return (
+    purpose === 'orderPayment' ||
+    purpose === 'subscriptionPayment' ||
+    purpose === 'deduction'
+  );
+}

package/templates/orionplace/COMPONENT-DOWNLOAD.md

@@ -0,0 +1,66 @@
+# React component source archive
+
+## English
+
+The archive contains the selected component, its local imports, CSS modules,
+shared theme and physical interfaces. Paths are relative to the React storefront
+project root. Keep the `@/` alias pointing to that root and preserve the directory
+structure when copying files.
+
+Use the archive inside an application initialized with `orionplace-react`. Its
+maintained package manifest supplies React, Next.js, Zustand and any imported
+third-party libraries. Components use the installed `OrionplaceProvider` and,
+where imported, `OrionplaceStorefrontProvider`. Initialize these providers from
+Application Load in the host application; callbacks and data props remain the
+application's responsibility. The selected component's README describes its
+specific request handlers and data requirements.
+
+`OrionplaceStorefrontProvider` runs the product card actions (cart, wishlist,
+stock alerts, preorders). When a guest clicks an action that needs an account,
+it opens the `/profile` sign-in page; pass `onSignIn={(location) => ...}` to
+open your own sign-in dialog instead. `location` holds the sign-in `path` and
+its `query`, including the `redirect` back to the current page.
+
+The provider also shows the preorder dialog over the page. With
+`preorderDialog={false}` it leaves the dialog to your page: render
+`ProductPreorderDialog` yourself (for example inline with `modal={false}`) from
+`preorder` (the product whose dialog is open), `preorderError` (its last
+refusal, for the dialog's `error`), `submitPreorder(selection)` and
+`closePreorder()` of `useOrionplaceStorefront()`; the card's preorder button
+still opens it through `onPreorder`.
+
+Import `app/globals.css` from the root layout. Component CSS modules and the
+shared theme are included with their original imports. This archive contains
+component source, not a separate application or backend configuration.
+
+## Русский
+
+Архив содержит выбранный компонент, его локальные зависимости, CSS-модули,
+общую тему и физические интерфейсы. Пути указаны относительно корня проекта
+React-магазина. Сохраните структуру каталогов и настройте `@/` на корень проекта.
+
+Используйте архив в приложении, созданном через `orionplace-react`. Его
+поддерживаемый список зависимостей включает React, Next.js, Zustand и необходимые
+сторонние библиотеки. Компоненты используют установленный `OrionplaceProvider`
+и, где он импортируется, `OrionplaceStorefrontProvider`. Приложение инициализирует
+провайдеры данными Application Load и передаёт входящие данные и обработчики.
+README выбранного компонента описывает нужные ему запросы и данные.
+
+`OrionplaceStorefrontProvider` выполняет действия карточки товара (корзина,
+избранное, уведомления о поступлении, предзаказ). Когда гость нажимает действие,
+для которого нужен аккаунт, провайдер открывает страницу входа `/profile`;
+передайте `onSignIn={(location) => ...}`, чтобы вместо неё открыть свой диалог
+входа. В `location` есть путь страницы входа `path` и её параметры `query`,
+включая `redirect` для возврата на текущую страницу.
+
+Провайдер также показывает окно предзаказа поверх страницы. С
+`preorderDialog={false}` он оставляет окно вашей странице: отрисуйте
+`ProductPreorderDialog` сами (например, встроенным с `modal={false}`) по
+`preorder` (товар, для которого открыто окно), `preorderError` (последний отказ
+для `error` окна), `submitPreorder(selection)` и `closePreorder()` из
+`useOrionplaceStorefront()`; кнопка предзаказа на карточке по-прежнему
+открывает его через `onPreorder`.
+
+Подключите `app/globals.css` в корневом макете. CSS-модули и общая тема включены
+с исходными импортами. Архив содержит исходники компонента; конфигурация
+подключения к API остаётся в приложении.