orionplace-react 0.1.0 → 0.2.1

package/templates/components/orionplace/cart/CartCheckoutDetails.README.md

@@ -0,0 +1,92 @@
+# CartCheckoutDetails
+
+## English
+
+`CartCheckoutDetails` shows the delivery address in both cart steps. During
+checkout it also shows the payment method, recipient and order comment. `data`
+is the latest `cart_guest_get` page data; `checkout` enables the checkout-only
+fields and `disabled` blocks every change while the parent cart is busy.
+
+The selected saved address is found by comparing the cart's `cart_address`
+copy with each item in `address_list`: label, street, house, apartment,
+entrance, intercom, floor, city, postal code, country ID and region ID must
+match. Empty and missing text are equal. If several addresses match, the
+shipping default is used first. When no address matches, the select shows the
+cart's copied address and explains that it is no longer saved. Only addresses in a delivery country (`country.is_shipping_country`) are offered; when others exist, a note says they are hidden. A new address abroad is saved, but not set for the cart, and a note asks to choose another address.
+
+Selecting a saved address calls `onChange` with
+`cart_customer_address_set`. The address form uses `addressFormProps`. After
+it returns a confirmed address list, the component closes it, calls `onReload`
+and selects the first returned address. The refreshed cart remains the source
+of the confirmed choice.
+
+Payment choices come from `payment_methods`, including each safe logo and its
+localized name. A choice calls `cart_customer_payment_set`. The «Choose
+payment method» prompt is listed only until a method is set: the backend
+cannot unset it. The recipient
+actions call `cart_customer_reciever_clean` or
+`cart_customer_reciever_set`; the latter sends `full_name` and `phonenumber`.
+The comment field takes up to 1024 characters; its own Save action sends
+`cart_customer_commentary_set` with `cart_commentary`. New cart data replaces the local recipient and comment
+drafts.
+
+On the Russian storefront a phone number typed without «+» the way it is written in Russia — «8 900 555-01-72» or «900 555-01-72» — becomes «+79005550172» when the field loses focus and before it is sent: the backend accepts only international numbers. A number typed with «+», other numbers and other languages are sent as typed (`phoneWithCountryCode()`).
+
+### Props
+
+| Prop                                                                                                  | Meaning                                                                                                       |
+| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `data?: { cart: ICartSummary; cart_data: IProduct[] \| ICartDelivery[]; will_not_ship: IProduct[]; }` | Current data rendered by the component.                                                                       |
+| `checkout?: boolean`                                                                                  | Current checkout step and customer selections.                                                                |
+| `disabled?: boolean`                                                                                  | Disables the component controls and prevents new actions.                                                     |
+| `addressFormProps?: Omit<AddressFormProps, "onSaved" \| "onCancel">`                                  | Props forwarded to the address form child component.                                                          |
+| `onChange?: (action: CartCheckoutDetailsAction) => Promise<unknown> \| unknown`                       | Called when the visitor confirms a new value. The callback payload is shown in its type.                      |
+| `onReload?: () => Promise<unknown> \| unknown`                                                        | Called when the checkout data must be loaded again. The callback has no payload.                              |
+| `onAddressSaved?: (addresses: IUserAddress[]) => void`                                                | Called when a delivery address has been saved and can be selected. The callback payload is shown in its type. |
+
+## Русский
+
+`CartCheckoutDetails` показывает адрес доставки на обоих шагах корзины. Во
+время оформления он также показывает способ оплаты, получателя и комментарий
+к заказу. `data` содержит последние данные страницы `cart_guest_get`.
+`checkout` включает поля оформления, а `disabled` блокирует изменения, пока
+родительская корзина выполняет запрос.
+
+Выбранный сохранённый адрес определяется сравнением копии `cart_address` с
+каждым элементом `address_list`. Должны совпасть название, улица, дом,
+квартира, подъезд, домофон, этаж, город, индекс, ID страны и ID региона.
+Пустой и отсутствующий текст считаются одинаковыми. Если совпало несколько
+адресов, первым используется основной адрес доставки. Если совпадений нет,
+поле показывает копию адреса из корзины и объясняет, что этого адреса больше
+нет среди сохранённых.
+
+Выбор сохранённого адреса вызывает `onChange` с
+`cart_customer_address_set`. Форма адреса получает `addressFormProps`. После
+возврата подтверждённого списка адресов компонент закрывает форму, вызывает
+`onReload` и выбирает первый возвращённый адрес. Подтверждённый выбор всегда
+берётся из следующего ответа корзины.
+
+Способы оплаты берутся из `payment_methods` вместе с безопасным логотипом и
+локализованным названием. Выбор вызывает `cart_customer_payment_set`.
+Подсказка «Выберите способ оплаты» есть в списке, только пока способ не выбран:
+бэкенд не умеет снимать выбор.
+Действия получателя вызывают `cart_customer_reciever_clean` или
+`cart_customer_reciever_set`; второй запрос передаёт `full_name` и
+`phonenumber`. Поле комментария принимает до 1024 символов; отдельное
+сохранение комментария вызывает `cart_customer_commentary_set` с
+`cart_commentary`. Новые данные корзины
+заменяют локальные значения получателя и комментария.
+
+В русской витрине номер без «+», набранный по-российски — «8 900 555-01-72» или «900 555-01-72», — при выходе из поля и перед отправкой становится «+79005550172»: бэкенд принимает только международный формат. Номер с «+», другие номера и другие языки отправляются как набраны (`phoneWithCountryCode()`).
+
+### Свойства
+
+| Свойство                                                                                              | Назначение                                                                                            |
+| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `data?: { cart: ICartSummary; cart_data: IProduct[] \| ICartDelivery[]; will_not_ship: IProduct[]; }` | Текущие данные, которые показывает компонент.                                                         |
+| `checkout?: boolean`                                                                                  | Текущий шаг оформления и выбор покупателя.                                                            |
+| `disabled?: boolean`                                                                                  | Блокирует элементы компонента и новые действия.                                                       |
+| `addressFormProps?: Omit<AddressFormProps, "onSaved" \| "onCancel">`                                  | Свойства, передаваемые дочернему компоненту формы адреса.                                             |
+| `onChange?: (action: CartCheckoutDetailsAction) => Promise<unknown> \| unknown`                       | Вызывается, когда покупатель подтверждает новое значение. Данные обработчика указаны в его типе.      |
+| `onReload?: () => Promise<unknown> \| unknown`                                                        | Вызывается, когда нужно заново загрузить данные оформления. Обработчик не получает данные.            |
+| `onAddressSaved?: (addresses: IUserAddress[]) => void`                                                | Вызывается, когда адрес доставки сохранён и его можно выбрать. Данные обработчика указаны в его типе. |

package/templates/components/orionplace/cart/CartCheckoutDetails.module.css

@@ -0,0 +1,159 @@
+.root,
+.panel,
+.form {
+  display: grid;
+  min-width: 0;
+  gap: 1.25rem;
+}
+
+
+.panel {
+  box-sizing: border-box;
+  padding: 1.25rem;
+  border: 1px solid var(--orionplace-border);
+  background: var(--orionplace-surface);
+  color: var(--orionplace-text);
+}
+
+.panel h2 {
+  margin: 0;
+  padding: 0;
+  font-size: 0.875rem;
+  line-height: calc(1.25 / 0.875);
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.heading,
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.heading { justify-content: space-between; }
+
+.textButton {
+  align-self: start;
+  padding: 0 0 0.125rem;
+  border: 0;
+  border-bottom: 1px solid currentColor;
+  color: var(--orionplace-text);
+  background: transparent;
+  font: inherit;
+  font-size: 0.75rem;
+  line-height: calc(1 / 0.75);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  cursor: pointer;
+}
+
+.textButton:focus-visible { opacity: 0.7; outline: none; }
+
+@media (hover: hover) {
+  .textButton:hover {
+    opacity: 0.7;
+    outline: none;
+  }
+}
+
+.button {
+  box-sizing: border-box;
+  display: inline-flex;
+  width: fit-content;
+  min-height: 2.75rem;
+  align-items: center;
+  justify-content: center;
+  padding: 0.65rem 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: calc(1 / 0.75);
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  cursor: pointer;
+}
+
+.button:focus-visible { background: var(--orionplace-hover); }
+
+@media (hover: hover) {
+  .button:hover {
+    background: var(--orionplace-hover);
+  }
+}
+
+.primary {
+  border-color: var(--orionplace-accent);
+  color: var(--orionplace-surface);
+  background: var(--orionplace-accent);
+}
+
+.primary:focus-visible {
+  background: var(--orionplace-accent);
+  opacity: 0.85;
+}
+
+@media (hover: hover) {
+  .primary:hover {
+    background: var(--orionplace-accent);
+    opacity: 0.85;
+  }
+}
+
+.button:disabled,
+.textButton:disabled {
+  cursor: not-allowed;
+  opacity: 0.4;
+}
+
+/* The panel's own fields; the embedded AddressForm styles its own. */
+.panel label:not([data-feature-part=AddressForm] *) {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 0.5rem;
+  color: var(--orionplace-muted);
+  font-size: 0.75rem;
+  line-height: calc(1 / 0.75);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.panel input:not([data-feature-part=AddressForm] *),
+.panel textarea:not([data-feature-part=AddressForm] *) {
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+  min-height: 2.75rem;
+  padding: 0.65rem 0.75rem;
+  border: 1px solid var(--orionplace-border);
+  border-radius: 0;
+  color: var(--orionplace-text);
+  background: var(--orionplace-surface);
+  font: inherit;
+  font-size: 0.875rem;
+  text-transform: none;
+  letter-spacing: normal;
+  outline: none;
+}
+
+.panel textarea:not([data-feature-part=AddressForm] *) { min-height: 7rem; resize: vertical; line-height: 1.5rem; }
+.panel input:not([data-feature-part=AddressForm] *):focus-visible,
+.panel textarea:not([data-feature-part=AddressForm] *):focus-visible { border-color: var(--orionplace-text); }
+.panel input:not([data-feature-part=AddressForm] *):disabled,
+.panel textarea:not([data-feature-part=AddressForm] *):disabled { cursor: not-allowed; opacity: 0.6; }
+.panel b:not([data-feature-part=AddressForm] *) { color: var(--orionplace-danger); font-weight: 400; }
+.muted { margin: 0; color: var(--orionplace-muted); font-size: 0.875rem; }
+.danger { margin: 0; color: var(--orionplace-danger); font-size: 0.875rem; line-height: 1.25rem; }
+.recipient { margin: 0; line-height: 1.5rem; }
+
+/* The cart's own width, not the screen's, as in the other packages. */
+@container (min-width: 592px) {
+  .panel { padding: 1.5rem; }
+}

package/templates/components/orionplace/cart/CartCheckoutDetails.tsx

@@ -0,0 +1,370 @@
+'use client';
+
+import { useEffect, useRef, useState, type FormEvent } from 'react';
+import { useOrionplaceSelections } from '@/providers/OrionplaceProvider';
+import type { IUserAddress } from '@/interfaces/orionplace/address/IUserAddress';
+import type {
+  ICartAddressRequest,
+  ICartCommentRequest,
+  ICartPaymentRequest,
+  ICartReceiverRequest,
+} from '@/interfaces/orionplace/cart/ICartActions';
+import { ECartState } from '@/interfaces/orionplace/cart/ICartActions';
+import type {
+  ICartGetResponse,
+  ICartSummary,
+} from '@/interfaces/orionplace/cart/ICartData';
+import { getAvailableValueFromObject } from '@/lib/orionplace/presentation';
+import {
+  canShipTo,
+  formatCartAddress,
+  matchCartAddress,
+} from '@/lib/orionplace/cartAddress';
+import { cartLabels } from '@/lib/orionplace/cartLabels';
+import { featureLabels } from '@/lib/orionplace/featureLabels';
+import { phoneWithCountryCode } from '@/lib/orionplace/phone';
+import {
+  AddressForm,
+  type AddressFormProps,
+} from '@/components/orionplace/address/AddressForm';
+import { OrionplaceSelect } from '@/components/orionplace/shared/OrionplaceSelect';
+import styles from './CartCheckoutDetails.module.css';
+
+type CartData = NonNullable<ICartGetResponse['page_data']>;
+
+function hasOtherRecipient(contact?: ICartSummary['contact']) {
+  const receiver = contact?.receiver;
+  const client = contact?.client;
+
+  return (
+    (receiver?.full_name ?? '') !== (client?.full_name ?? '') ||
+    (receiver?.phone ?? '') !== (client?.phone ?? '')
+  );
+}
+
+export type CartCheckoutDetailsAction =
+  | {
+      endpoint: 'cart_customer_address_set';
+      request: ICartAddressRequest;
+    }
+  | {
+      endpoint: 'cart_customer_payment_set';
+      request: ICartPaymentRequest;
+    }
+  | {
+      endpoint: 'cart_customer_reciever_set';
+      request: ICartReceiverRequest;
+    }
+  | {
+      endpoint: 'cart_customer_reciever_clean';
+      request: Record<string, never>;
+    }
+  | {
+      endpoint: 'cart_customer_commentary_set';
+      request: ICartCommentRequest;
+    };
+
+export interface CartCheckoutDetailsProps {
+  data?: CartData | null;
+  checkout?: boolean;
+  disabled?: boolean;
+  addressFormProps?: Omit<AddressFormProps, 'onSaved' | 'onCancel' | 'onDone'>;
+  onChange?: (
+    action: CartCheckoutDetailsAction,
+  ) => Promise<unknown> | unknown;
+  onReload?: () => Promise<unknown> | unknown;
+  onAddressSaved?: (addresses: IUserAddress[]) => void;
+}
+
+export function CartCheckoutDetails({
+  data,
+  checkout,
+  disabled = false,
+  addressFormProps,
+  onChange,
+  onReload,
+  onAddressSaved,
+}: CartCheckoutDetailsProps) {
+  const locale = useOrionplaceSelections((state) => state.localeCode);
+  const labels = cartLabels(locale);
+  const common = featureLabels(locale);
+  const summary = data?.cart;
+  const inCheckout = checkout ?? (
+    summary?.state === ECartState.STATE_CHECKOUT
+  );
+  const [showsAddressForm, setShowsAddressForm] = useState(false);
+  const [comment, setComment] = useState(summary?.comment ?? '');
+  const [name, setName] = useState(
+    summary?.contact.receiver?.full_name ?? '',
+  );
+  const [phone, setPhone] = useState(summary?.contact.receiver?.phone ?? '');
+  const [otherRecipient, setOtherRecipient] = useState(
+    () => hasOtherRecipient(summary?.contact),
+  );
+  const disabledRef = useRef(disabled);
+  disabledRef.current = disabled;
+
+  const [savedAbroad, setSavedAbroad] = useState(false);
+  // Only addresses in delivery countries can be chosen; the backend refuses
+  // the others.
+  const shippable = (summary?.address_list ?? []).filter(canShipTo);
+  const abroad = (summary?.address_list ?? []).some((item) => !canShipTo(item));
+  const selectedAddress = matchCartAddress(summary?.cart_address, shippable);
+  const unsavedAddress = Boolean(summary?.cart_address) && selectedAddress === 0;
+  const savedAddresses = Object.fromEntries(
+    shippable.map((address) => [
+      String(address.id),
+      formatCartAddress(address),
+    ]),
+  );
+  const addresses = selectedAddress > 0
+    ? savedAddresses
+    : {
+        0: summary?.cart_address
+          ? formatCartAddress(summary.cart_address)
+          : labels.chooseAddress,
+        ...savedAddresses,
+      };
+  const methods = Object.values(summary?.payment_methods ?? {});
+  // The prompt is offered only until a method is set: the backend cannot
+  // unset it, so picking the prompt again would show a choice it ignores.
+  const paymentChosen = methods.some(
+    (method) => method.id === summary?.selected_payment,
+  );
+  const payments = {
+    ...(paymentChosen ? {} : { 0: labels.choosePayment }),
+    ...Object.fromEntries(methods.map((method) => [
+      String(method.id),
+      getAvailableValueFromObject(method.locale, locale)?.payment_name ||
+        `#${method.id}`,
+    ])),
+  };
+  const paymentIcons = Object.fromEntries(
+    methods.map((method) => [String(method.id), method.logo]),
+  );
+
+  useEffect(() => {
+    const receiver = summary?.contact.receiver;
+    const nextName = receiver?.full_name ?? '';
+    const nextPhone = receiver?.phone ?? '';
+    setName(nextName);
+    setPhone(nextPhone);
+    setOtherRecipient(hasOtherRecipient(summary?.contact));
+  }, [summary?.contact]);
+
+  useEffect(() => {
+    setComment(summary?.comment ?? '');
+  }, [summary?.comment]);
+
+  // The form stays open on the saved address until the customer closes it.
+  async function addressSaved(addresses: IUserAddress[]) {
+    // Read before the reload: until React renders its result, the ref still
+    // holds the reload's own busy state and would skip the new address.
+    const blocked = disabledRef.current;
+    onAddressSaved?.(addresses);
+    await onReload?.();
+    const added = addresses[0];
+    const abroadAdded = added !== undefined && !canShipTo(added);
+    setSavedAbroad(abroadAdded);
+    if (added && !abroadAdded && !blocked) {
+      await onChange?.({
+        endpoint: 'cart_customer_address_set',
+        request: { address: added.id },
+      });
+    }
+  }
+
+  function selectAddress(value: string) {
+    const address = Number(value);
+    if (address > 0 && address !== selectedAddress) {
+      setSavedAbroad(false);
+      void onChange?.({
+        endpoint: 'cart_customer_address_set',
+        request: { address },
+      });
+    }
+  }
+
+  function selectPayment(value: string) {
+    const payment = Number(value);
+    if (payment > 0 && payment !== summary?.selected_payment) {
+      void onChange?.({
+        endpoint: 'cart_customer_payment_set',
+        request: { payment },
+      });
+    }
+  }
+
+  function saveRecipient(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const phonenumber = phoneWithCountryCode(phone, locale);
+    setPhone(phonenumber);
+    void onChange?.({
+      endpoint: 'cart_customer_reciever_set',
+      request: { full_name: name, phonenumber },
+    });
+  }
+
+  function saveComment(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    void onChange?.({
+      endpoint: 'cart_customer_commentary_set',
+      request: { cart_commentary: comment },
+    });
+  }
+
+  return (
+    <div className={styles.root} data-feature-part="CartCheckoutDetails">
+      <section className={styles.panel}>
+        <div className={styles.heading}>
+          <h2>{labels.address}</h2>
+          <button
+            type="button"
+            className={styles.textButton}
+            disabled={disabled}
+            onClick={() => setShowsAddressForm((value) => !value)}
+          >
+            {labels.addAddress}
+          </button>
+        </div>
+        {showsAddressForm ? (
+          <AddressForm
+            {...addressFormProps}
+            pending={disabled || addressFormProps?.pending}
+            onSaved={(values) => void addressSaved(values)}
+            onDone={() => setShowsAddressForm(false)}
+            onCancel={() => setShowsAddressForm(false)}
+          />
+        ) : (
+          <>
+            <OrionplaceSelect
+              value={String(selectedAddress)}
+              options={addresses}
+              label={labels.selectedAddress}
+              disabled={disabled}
+              required
+              onValueChange={selectAddress}
+            />
+            {unsavedAddress ? (
+              <p className={styles.muted} data-cart-unsaved-address>
+                {labels.unsavedAddress}
+              </p>
+            ) : null}
+            {savedAbroad ? (
+              <p
+                className={styles.danger}
+                role="status"
+                data-address-no-shipping
+              >
+                {labels.savedAbroad}
+              </p>
+            ) : abroad ? (
+              <p className={styles.muted}>{labels.abroadHidden}</p>
+            ) : null}
+          </>
+        )}
+      </section>
+
+      {inCheckout ? (
+        <>
+          <section className={styles.panel}>
+            <h2>{labels.payment}</h2>
+            <OrionplaceSelect
+              value={String(summary?.selected_payment ?? 0)}
+              options={payments}
+              icons={paymentIcons}
+              label={labels.payment}
+              disabled={disabled}
+              required
+              onValueChange={selectPayment}
+            />
+          </section>
+
+          <section className={styles.panel}>
+            <h2>{labels.recipient}</h2>
+            <p className={styles.recipient}>
+              {summary?.contact.receiver?.full_name || ''} ·{' '}
+              {summary?.contact.receiver?.phone || ''}
+            </p>
+            <div className={styles.actions}>
+              <button
+                type="button"
+                className={styles.button}
+                disabled={disabled}
+                aria-label={labels.myselfHint}
+                onClick={() => void onChange?.({
+                  endpoint: 'cart_customer_reciever_clean',
+                  request: {},
+                })}
+              >
+                {labels.myself}
+              </button>
+              <button
+                type="button"
+                className={styles.button}
+                disabled={disabled}
+                aria-label={labels.otherRecipientHint}
+                onClick={() => setOtherRecipient((value) => !value)}
+              >
+                {labels.otherRecipient}
+              </button>
+            </div>
+            {otherRecipient ? (
+              <form className={styles.form} onSubmit={saveRecipient}>
+                <label>
+                  <span>{labels.name} <b aria-hidden="true">*</b></span>
+                  <input
+                    value={name}
+                    required
+                    maxLength={100}
+                    autoComplete="name"
+                    disabled={disabled}
+                    onChange={(event) => setName(event.target.value)}
+                  />
+                </label>
+                <label>
+                  <span>{labels.phone} <b aria-hidden="true">*</b></span>
+                  <input
+                    value={phone}
+                    type="tel"
+                    required
+                    autoComplete="tel"
+                    disabled={disabled}
+                    onChange={(event) => setPhone(event.target.value)}
+                    onBlur={() => setPhone(phoneWithCountryCode(phone, locale))}
+                  />
+                </label>
+                <button
+                  type="submit"
+                  className={`${styles.button} ${styles.primary}`.trim()}
+                  disabled={disabled}
+                >
+                  {common.save}
+                </button>
+              </form>
+            ) : null}
+          </section>
+
+          <form className={styles.panel} onSubmit={saveComment}>
+            <label>
+              <span>{labels.comment}</span>
+              <textarea
+                value={comment}
+                maxLength={1024}
+                disabled={disabled}
+                onChange={(event) => setComment(event.target.value)}
+              />
+            </label>
+            <button
+              type="submit"
+              className={`${styles.button} ${styles.primary}`.trim()}
+              disabled={disabled}
+            >
+              {common.save}
+            </button>
+          </form>
+        </>
+      ) : null}
+    </div>
+  );
+}