orionplace-react 0.1.0 → 0.2.1

package/templates/lib/orionplace/orderPresentation.ts

@@ -0,0 +1,574 @@
+import {
+  EOrderPaymentStatus,
+  EOrderStatus,
+} from '@/interfaces/orionplace/orders/IOrderActions';
+import { getAvailableValueFromObject } from '@/lib/orionplace/presentation';
+import type {
+  IOrder,
+  IOrderItemRefundStats,
+  IOrderOption,
+  IOrderOptionGroup,
+  IOrderShipment,
+  IOrderShipmentItem,
+  OrderRefundWindow,
+} from '@/interfaces/orionplace/orders/IOrderHistory';
+import type { ICurrencyAmounts } from '@/interfaces/orionplace/cart/ICartData';
+import type { IProduct } from '@/interfaces/orionplace/products/IProduct';
+import type {
+  ICustomerTicket,
+  ICustomerTicketRefund,
+} from '@/interfaces/orionplace/tickets/ICustomerTicketApi';
+
+export type OrderBadgeTone = 'neutral' | 'progress' | 'success' | 'danger';
+
+export type OrderIconName =
+  | 'clock'
+  | 'truck'
+  | 'check'
+  | 'close'
+  | 'return'
+  | 'card'
+  | 'download'
+  | 'pin'
+  | 'user'
+  | 'box';
+
+export type OrderStatusKey =
+  | 'processing'
+  | 'shipped'
+  | 'partlyShipped'
+  | 'delivered'
+  | 'partlyDelivered'
+  | 'canceled'
+  | 'refund';
+
+export type OrderPaymentKey =
+  'notPaid' | 'partlyPaid' | 'onDelivery' | 'paid' | 'paidAfterCancel';
+
+export interface OrderBadge<Key extends string> {
+  key: Key;
+  tone: OrderBadgeTone;
+  icon: OrderIconName;
+}
+
+export type OrderStepKey = 'placed' | 'shipped' | 'delivered';
+
+export interface OrderStep {
+  key: OrderStepKey;
+  state: 'done' | 'partial' | 'todo';
+  current: boolean;
+  count: number;
+  total: number;
+}
+
+export type OrderShipmentStateKey =
+  'preparing' | 'sent' | 'delivered' | 'canceled' | 'returned';
+
+export type OrderRefundCountKey =
+  | 'awaiting'
+  | 'received'
+  | 'approved'
+  | 'defect';
+
+export interface OrderRefundCount {
+  key: OrderRefundCountKey;
+  count: number;
+}
+
+export interface OrderRefundView {
+  counts: OrderRefundCount[];
+  amount?: ICurrencyAmounts;
+  package?: ICustomerTicketRefund;
+  ticketId?: number;
+  // The return request the line accepts now, null when none.
+  window: OrderRefundWindow | null;
+  canRequest: boolean;
+  active: boolean;
+}
+
+type OrderShipmentCounters = Pick<
+  IOrder,
+  | 'status'
+  | 'c_delivery_from'
+  | 'c_delivery_from_sent'
+  | 'c_delivery_from_delivered'
+> &
+  Partial<Pick<IOrder, 'delivery_froms'>>;
+
+export interface OrderShipmentProgress {
+  total: number;
+  sent: number;
+  delivered: number;
+}
+
+// 24 × 24 stroke paths shared by the order components.
+export const orderIconPaths: Record<OrderIconName, string> = {
+  clock: 'M12 7v5l3 2M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z',
+  truck:
+    'M3 6h11v10H3zM14 10h4l3 3v3h-7M7.5 19a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3ZM17.5 19a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3Z',
+  check: 'm5 12.5 4.5 4.5L19 7.5',
+  close: 'M6 6l12 12M18 6 6 18',
+  return: 'M9 14 4 9l5-5M4 9h11a5 5 0 0 1 0 10h-3',
+  card: 'M3 6h18v12H3zM3 10h18M7 15h4',
+  download: 'M12 4v11m0 0-4.5-4.5M12 15l4.5-4.5M5 20h14',
+  pin: 'M12 21s-7-6.2-7-11.5a7 7 0 0 1 14 0C19 14.8 12 21 12 21ZM12 12a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5Z',
+  user: 'M12 12a4 4 0 1 0 0-8 4 4 0 0 0 0 8ZM4 21a8 8 0 0 1 16 0',
+  box: 'M3 7.5 12 3l9 4.5v9L12 21l-9-4.5zM3 7.5 12 12l9-4.5M12 12v9',
+};
+
+export function orderAmount(
+  amounts: ICurrencyAmounts | null | undefined,
+  currencyId: string | number,
+) {
+  const value = Number(amounts?.[String(currencyId)]?.transform_value);
+
+  return Number.isFinite(value) ? value : undefined;
+}
+
+export function hasOrderAmount(
+  amounts: ICurrencyAmounts | null | undefined,
+  currencyId: string | number,
+) {
+  return (orderAmount(amounts, currencyId) ?? 0) > 0;
+}
+
+// A shipment counts as shipped once it has a sent date and as delivered once
+// it has a delivery date. The order is shipped or delivered only when every
+// shipment is; otherwise it is partly shipped or partly delivered. The order
+// counters are used only when the response carries no shipments.
+export function orderShipmentProgress(
+  order: OrderShipmentCounters,
+): OrderShipmentProgress {
+  const shipments = order.delivery_froms ?? [];
+
+  if (!shipments.length) {
+    const delivered = order.c_delivery_from_delivered;
+
+    return {
+      total: order.c_delivery_from,
+      sent: Math.max(order.c_delivery_from_sent, delivered),
+      delivered,
+    };
+  }
+
+  const delivered = shipments.filter(
+    (shipment) => shipment.dates?.delivery_date_real,
+  ).length;
+  const sent = shipments.filter(
+    (shipment) => shipment.dates?.sent || shipment.dates?.delivery_date_real,
+  ).length;
+
+  return { total: shipments.length, sent, delivered };
+}
+
+export function orderStatusBadge(
+  order: OrderShipmentCounters,
+): OrderBadge<OrderStatusKey> {
+  const { total, sent, delivered } = orderShipmentProgress(order);
+
+  if (order.status.int === EOrderStatus.CANCELED) {
+    return { key: 'canceled', tone: 'danger', icon: 'close' };
+  }
+  if (order.status.int === EOrderStatus.REFUND) {
+    return { key: 'refund', tone: 'neutral', icon: 'return' };
+  }
+  if (total > 0 && delivered >= total) {
+    return { key: 'delivered', tone: 'success', icon: 'check' };
+  }
+  if (delivered > 0) {
+    return { key: 'partlyDelivered', tone: 'progress', icon: 'truck' };
+  }
+  if (total > 0 && sent >= total) {
+    return { key: 'shipped', tone: 'progress', icon: 'truck' };
+  }
+  if (sent > 0) {
+    return { key: 'partlyShipped', tone: 'progress', icon: 'truck' };
+  }
+
+  return { key: 'processing', tone: 'neutral', icon: 'clock' };
+}
+
+export function orderPaymentBadge(
+  order: Pick<
+    IOrder,
+    'status' | 'payment_status' | 'pay_on_delivery' | 'prices'
+  >,
+  currencyId: string | number,
+): OrderBadge<OrderPaymentKey> {
+  const status = order.payment_status.int;
+  const canceled = order.status.int === EOrderStatus.CANCELED;
+
+  if (status === EOrderPaymentStatus.LATE_PAID) {
+    return { key: 'paidAfterCancel', tone: 'neutral', icon: 'card' };
+  }
+  if (status === EOrderPaymentStatus.PAID) {
+    return { key: 'paid', tone: 'success', icon: 'check' };
+  }
+  if (hasOrderAmount(order.prices.order_total_paid, currencyId)) {
+    return { key: 'partlyPaid', tone: 'progress', icon: 'card' };
+  }
+  if (order.pay_on_delivery) {
+    return { key: 'onDelivery', tone: 'neutral', icon: 'card' };
+  }
+
+  return {
+    key: 'notPaid',
+    tone: canceled ? 'neutral' : 'danger',
+    icon: 'card',
+  };
+}
+
+export function orderCanCancel(
+  order: Pick<IOrder, 'status' | 'payment_status'>,
+) {
+  return (
+    order.status.int === EOrderStatus.CREATED &&
+    order.payment_status.int === EOrderPaymentStatus.NOT_PAID
+  );
+}
+
+// Canceled and returned orders have no delivery progress to show.
+export function orderSteps(order: OrderShipmentCounters): OrderStep[] {
+  const { total, sent, delivered } = orderShipmentProgress(order);
+
+  if (
+    order.status.int === EOrderStatus.CANCELED ||
+    order.status.int === EOrderStatus.REFUND
+  ) {
+    return [];
+  }
+
+  const steps = [
+    { key: 'placed', state: 'done', current: false, count: 1, total: 1 },
+    {
+      key: 'shipped',
+      state: stepState(sent, total),
+      current: false,
+      count: sent,
+      total,
+    },
+    {
+      key: 'delivered',
+      state: stepState(delivered, total),
+      current: false,
+      count: delivered,
+      total,
+    },
+  ] satisfies OrderStep[];
+
+  return markCurrentStep(steps);
+}
+
+// The order stands on the last step it has reached, fully or partly: Placed
+// while no shipment has left, Shipped once some or all have been sent and
+// Delivered once some or all have arrived.
+function markCurrentStep(steps: OrderStep[]) {
+  const reached = steps.filter((step) => step.state !== 'todo');
+  const current = reached[reached.length - 1];
+
+  if (current) {
+    current.current = true;
+  }
+
+  return steps;
+}
+
+function stepState(count: number, total: number): OrderStep['state'] {
+  if (total > 0 && count >= total) {
+    return 'done';
+  }
+
+  return count > 0 ? 'partial' : 'todo';
+}
+
+// Each shipment carries its own dates, so one order can hold a delivered
+// shipment beside another that is still being prepared.
+export function orderShipmentState(
+  order: Pick<IOrder, 'status'>,
+  shipment: Pick<IOrderShipment, 'dates'>,
+): OrderBadge<OrderShipmentStateKey> {
+  if (order.status.int === EOrderStatus.CANCELED) {
+    return { key: 'canceled', tone: 'danger', icon: 'close' };
+  }
+  // The carrier brought the package back undelivered; its units are
+  // returned and refunded.
+  if (shipment.dates?.returned_by_carrier) {
+    return { key: 'returned', tone: 'danger', icon: 'return' };
+  }
+  if (shipment.dates?.delivery_date_real) {
+    return { key: 'delivered', tone: 'success', icon: 'check' };
+  }
+  if (shipment.dates?.sent) {
+    return { key: 'sent', tone: 'progress', icon: 'truck' };
+  }
+
+  return { key: 'preparing', tone: 'neutral', icon: 'clock' };
+}
+
+export function orderShipmentItems(
+  order: Pick<IOrder, 'delivery_froms'>,
+): IOrderShipmentItem[] {
+  return (order.delivery_froms ?? []).flatMap(
+    (shipment) => shipment.shipment_items ?? [],
+  );
+}
+
+export function orderQuantity(order: Pick<IOrder, 'delivery_froms'>) {
+  return orderShipmentItems(order).reduce(
+    (total, item) => total + (Number(item.quantity) || 0),
+    0,
+  );
+}
+
+// Shows every item up to the limit; otherwise the last slot becomes “+N”.
+export function orderThumbnails<Item>(items: Item[], limit = 4) {
+  if (items.length <= limit) {
+    return { items, extra: 0 };
+  }
+
+  const visible = items.slice(0, Math.max(limit - 1, 0));
+
+  return { items: visible, extra: items.length - visible.length };
+}
+
+// The backend stores the amount of a whole line; one piece is that amount
+// divided by the ordered quantity.
+function unitPrice(total: number | undefined, quantity: number) {
+  if (total === undefined || !quantity) {
+    return undefined;
+  }
+
+  return Math.round((total / quantity) * 100) / 100;
+}
+
+export function orderUnitPrice(
+  item: Pick<IOrderShipmentItem, 'quantity' | 'prices'>,
+  currencyId: string | number,
+) {
+  return unitPrice(
+    orderAmount(item.prices.products_price_after_promo, currencyId),
+    item.quantity,
+  );
+}
+
+// An option row keeps the amount of its own line, options only, in
+// `prices.options_price_after_promo`.
+export function orderOptionUnitPrice(
+  option: Pick<IOrderOption, 'quantity' | 'prices'>,
+  currencyId: string | number,
+) {
+  return unitPrice(
+    orderAmount(option.prices?.options_price_after_promo, currencyId),
+    option.quantity,
+  );
+}
+
+export function orderItemVariant(product: IProduct | null, locale: string) {
+  const variant = product?.variants?.main_variant;
+  const value = variant?.value.find(
+    (entry) => entry.reload_product === product?.id,
+  );
+
+  if (!variant || !value) {
+    return '';
+  }
+
+  const name = getAvailableValueFromObject(variant.locale, locale) ?? '';
+  const label = getAvailableValueFromObject(value.locale, locale) ?? '';
+
+  return [name, label].filter(Boolean).join(': ');
+}
+
+// The backend counts the units of a return in three separate stages, and one
+// item can hold more than one of them at the same time, so each stage that
+// still has units keeps its own row. The units returned as defective are a
+// part of the received and approved ones and get a row of their own.
+const refundStages: [OrderRefundCountKey, keyof IOrderItemRefundStats][] = [
+  ['awaiting', 'c_refund_wait'],
+  ['received', 'c_refund_delivered'],
+  ['approved', 'c_refund_to_pay'],
+  ['defect', 'c_refund_defect'],
+];
+
+function refundCount(value: unknown) {
+  const count = Number(value ?? 0);
+
+  return Number.isFinite(count) && count > 0 ? Math.floor(count) : 0;
+}
+
+function refundCounts(stats: IOrderItemRefundStats | undefined) {
+  const counts: OrderRefundCount[] = [];
+
+  for (const [key, field] of refundStages) {
+    const count = refundCount(stats?.[field]);
+
+    if (count > 0) {
+      counts.push({ key, count });
+    }
+  }
+
+  return counts;
+}
+
+/**
+ * The return request a line accepts now: `regular` inside the return
+ * period, `defect` after it while only a defect can be reported, null when
+ * no request is accepted. A backend without `refund_window` sends only
+ * `refund_allowed`, which reads as the regular period.
+ */
+export function orderRefundWindow(
+  line: Partial<Pick<IOrderShipmentItem, 'refund_allowed' | 'refund_window'>>,
+): OrderRefundWindow | null {
+  if (line.refund_window !== undefined) {
+    return line.refund_window === 'regular' || line.refund_window === 'defect'
+      ? line.refund_window
+      : null;
+  }
+
+  return line.refund_allowed ? 'regular' : null;
+}
+
+/**
+ * The units of a digital line or option whose content was returned. The
+ * backend stops listing returned content, so the line shows this count
+ * instead; a line of physical goods always gives 0.
+ */
+export function orderDigitalReturned(
+  line: Pick<IOrderShipmentItem, 'product' | 'quantity' | 'refund_stats'>,
+) {
+  if (!line.product?.is_digital) {
+    return 0;
+  }
+
+  const returned = refundCount(line.refund_stats?.c_refund_delivered) +
+    refundCount(line.refund_stats?.c_refund_to_pay);
+
+  return Math.min(returned, refundCount(line.quantity));
+}
+
+function refundView(
+  stats: IOrderItemRefundStats | undefined,
+  amounts: ICurrencyAmounts | null | undefined,
+  currencyId: string | number,
+  extra: { window?: OrderRefundWindow | null; ticket?: ICustomerTicket } = {},
+): OrderRefundView {
+  const counts     = refundCounts(stats);
+  const amount     = hasOrderAmount(amounts, currencyId) ? amounts : undefined;
+  const refundPack = extra.ticket?.refund;
+  const window     = extra.window ?? null;
+  const canRequest = window !== null && !extra.ticket;
+
+  return {
+    counts,
+    amount: amount ?? undefined,
+    package: refundPack,
+    ticketId: extra.ticket?.id,
+    window,
+    canRequest,
+    active: Boolean(counts.length || amount || refundPack),
+  };
+}
+
+// The amount of an item covers its products only; every option keeps its own.
+export function orderItemRefund(
+  item: Pick<
+    IOrderShipmentItem,
+    'prices' | 'refund_allowed' | 'refund_window' | 'refund_stats' | 'ticket'
+  >,
+  currencyId: string | number,
+) {
+  return refundView(
+    item.refund_stats,
+    item.prices?.products_refund_price_to_pay,
+    currencyId,
+    { window: orderRefundWindow(item), ticket: item.ticket },
+  );
+}
+
+export function orderOptionRefund(
+  option: Pick<
+    IOrderOption,
+    'prices' | 'refund_allowed' | 'refund_window' | 'refund_stats' | 'ticket'
+  >,
+  currencyId: string | number,
+) {
+  return refundView(
+    option.refund_stats,
+    option.prices?.refund_price_to_pay,
+    currencyId,
+    { window: orderRefundWindow(option), ticket: option.ticket },
+  );
+}
+
+export interface OrderRefundEntry {
+  key: string;
+  product: IProduct | null;
+  quantity: number;
+  refund: OrderRefundView;
+}
+
+// A return shipment covers items from the whole order, so its list is built
+// from every item and option that still carries a return count.
+export function orderRefundEntries(
+  order: Pick<IOrder, 'delivery_froms'> | null | undefined,
+  currencyId: string | number,
+): OrderRefundEntry[] {
+  const entries: OrderRefundEntry[] = [];
+
+  for (const shipment of order?.delivery_froms ?? []) {
+    for (const item of shipment.shipment_items ?? []) {
+      const itemRefund = orderItemRefund(item, currencyId);
+
+      if (itemRefund.counts.length) {
+        entries.push({
+          key: `item-${item.id}`,
+          product: item.product,
+          quantity: item.quantity,
+          refund: itemRefund,
+        });
+      }
+
+      for (const group of item.option_groups ?? []) {
+        for (const option of group.options ?? []) {
+          const optionRefund = orderOptionRefund(option, currencyId);
+
+          if (optionRefund.counts.length) {
+            entries.push({
+              key: `option-${option.id}`,
+              product: option.product,
+              quantity: option.quantity,
+              refund: optionRefund,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * The option groups of an ordered item as the customer filled them in: only
+ * options ordered in a positive quantity, and only groups that hold a text,
+ * a file or at least one such option. A group left empty was not part of
+ * the order and is not shown.
+ */
+export function orderFilledOptionGroups(
+  item: Pick<IOrderShipmentItem, 'option_groups'>,
+): IOrderOptionGroup[] {
+  const groups: IOrderOptionGroup[] = [];
+
+  for (const group of item.option_groups ?? []) {
+    const options = (group.options ?? []).filter(
+      (option) => option.quantity > 0,
+    );
+    const text    = (group.option_text_data ?? '').trim();
+
+    if (text || group.option_file_data || options.length) {
+      groups.push({ ...group, options });
+    }
+  }
+
+  return groups;
+}