orionplace-react 0.1.0 → 0.2.0

package/templates/components/orionplace/products/ProductSpecificationsDialog.tsx

@@ -0,0 +1,117 @@
+'use client';
+
+import '@/components/orionplace/shared/dialogs.css';
+
+import { StorefrontLink as Link } from '@/lib/orionplace/navigation';
+import { useEffect, useRef, type MouseEvent } from 'react';
+import { useOrionplaceSelections } from '@/providers/OrionplaceProvider';
+import type { IProductSpecificationGroup } from '@/interfaces/orionplace/products/IProductSpecification';
+import { featureLabels } from '@/lib/orionplace/featureLabels';
+import { reviewLabels } from '@/lib/orionplace/reviewLabels';
+import {
+  createPageScrollLock,
+  restoreFocus,
+} from '@/lib/orionplace/modalWindow';
+import styles from './ProductSpecificationsDialog.module.css';
+
+export interface ProductSpecificationsDialogProps {
+  groups: IProductSpecificationGroup[];
+  onClose?: () => void;
+}
+
+export function ProductSpecificationsDialog({
+  groups,
+  onClose,
+}: ProductSpecificationsDialogProps) {
+  const locale = useOrionplaceSelections((state) => state.localeCode);
+  const labels = reviewLabels(locale);
+  const common = featureLabels(locale);
+  const dialog = useRef<HTMLDialogElement>(null);
+
+  function backdrop(event: MouseEvent<HTMLDialogElement>) {
+    const element = dialog.current;
+    if (!element || event.target !== element) {
+      return;
+    }
+    const bounds = element.getBoundingClientRect();
+    if (
+      event.clientX < bounds.left ||
+      event.clientX > bounds.right ||
+      event.clientY < bounds.top ||
+      event.clientY > bounds.bottom
+    ) {
+      onClose?.();
+    }
+  }
+
+  useEffect(() => {
+    const element    = dialog.current;
+    const pageScroll = createPageScrollLock();
+    const opener     =
+      document.activeElement instanceof HTMLElement
+        ? document.activeElement
+        : undefined;
+    pageScroll.lock();
+    element?.showModal();
+
+    return () => {
+      element?.close();
+      pageScroll.unlock();
+      restoreFocus(opener);
+    };
+  }, []);
+
+  return (
+    <dialog
+      data-stable-modal="wide"
+      ref={dialog}
+      className={styles.dialog}
+      aria-label={labels.characteristics}
+      data-feature-part="ProductSpecificationsDialog"
+      data-product-specifications-dialog
+      onCancel={(event) => {
+        event.preventDefault();
+        onClose?.();
+      }}
+      onClick={backdrop}
+    >
+      <div className={styles.layout}>
+        <header>
+          <h2>{labels.characteristics}</h2>
+          <button
+            type="button"
+            aria-label={common.close}
+            data-product-specifications-close
+            onClick={() => onClose?.()}
+          >
+            <span aria-hidden="true">×</span>
+          </button>
+        </header>
+        <div className={styles.body} tabIndex={0} data-product-specifications-body>
+          {groups.map((group) => (
+            <div key={group.key} className={styles.group}>
+              {group.title ? <h3>{group.title}</h3> : null}
+              <dl>
+                {group.rows.map((row) => (
+                  <div key={row.key}>
+                    <dt>{row.label}</dt>
+                    <dd>
+                      {row.to ? (
+                        <Link
+                          href={{ pathname: row.to.path, query: row.to.query }}
+                          onClick={() => onClose?.()}
+                        >
+                          {row.value}
+                        </Link>
+                      ) : row.value}
+                    </dd>
+                  </div>
+                ))}
+              </dl>
+            </div>
+          ))}
+        </div>
+      </div>
+    </dialog>
+  );
+}

package/templates/components/orionplace/products/StorefrontProduct.README.md

@@ -0,0 +1,200 @@
+# StorefrontProduct · React
+
+## English
+
+`StorefrontProduct` presents one complete product page: category path, image
+gallery, price and purchase controls, description, characteristics, return
+periods, manufacturer, seller and reviews.
+
+For server rendering, load the product before rendering and pass it as
+`initialProduct` with `preloaded=true`, or put it in the provider's product
+store and set `preloaded=true`. The first HTML then contains the product name,
+price and plain-text description. The browser sanitizes and restores the
+description's supported formatting after hydration without sending another
+product request.
+
+When the product is not preloaded, `loadOnMount` calls `onLoad`. The callback
+receives `products_search`, `filters.id = productId` and the request's
+`AbortSignal`. A non-empty `previewKey` changes the endpoint to
+`products_preview` and adds `filters.view_key`. Return the matching `IProduct`;
+return `undefined` after a successful empty response so the component can call
+`onMissing`. A rejected request keeps the error and Retry repeats the same
+request. `onLoaded` receives the product shown by the page, including a loaded
+variant.
+
+The gallery uses full images when available and otherwise uses small images.
+Previous and next controls wrap around. The thumbnail rail scrolls only when
+its images do not fit; arrow keys select adjacent images, while Home and End
+select the first and last. A tap, click or Enter on the main image opens the
+photos in `ProductReviewImageViewer`; the photo chosen there stays selected.
+Every image reserves display space while it loads.
+
+The localized product description is rendered as safe plain paragraphs on the
+server and sanitized editor HTML in the browser. Long descriptions collapse
+behind More. Characteristics include the manufacturer, positive weight, all
+three positive dimensions, digital-product type and localized attribute
+groups. The current weight and length selections choose the displayed units.
+A list that exceeds its reserved space opens every row in
+`ProductSpecificationsDialog`.
+
+The details card forwards cart, wishlist, availability and variant events
+through the matching `onAdd`, `onRemove`, `onToggleFavorite`, `onSubscribe`,
+`onUnsubscribe`, `onRequestSecondaryVariants`, `onSelectVariant` and
+`onSelectSecondaryVariant` callbacks. When a requested variant appears in the
+product store, the heading, gallery, description, characteristics and reviews
+switch to that product. `actionPending` and `needsRefresh` disable new purchase
+actions. `actionNotice` shows confirmed feedback; `onRetryRefresh` handles the
+reload action after an accepted mutation whose refresh failed.
+
+Selecting Preorder opens `ProductPreorderDialog`. `onSubmitPreorder` receives
+the exact `preorders_create` request, including the product ID and trimmed guest
+contact values. Returning `false` keeps the dialog open. A resolved response
+closes it, while a rejected response leaves a visible error and permits retry.
+Field errors of an `OrionplaceApiError` appear under the email and phone
+fields. When the backend answers with the code `sign_in` (a guest used a
+registered customer's contact), the dialog shows a Sign in button that calls
+`onSignIn`.
+
+`reviewProps` passes the current review data and typed review actions to
+`ProductReviews`. The review summary uses `feedback_stat`; selecting it scrolls
+to the reviews. Physical products show each positive return period. Digital
+products hide returns. The manufacturer link uses `manufacture.id`. The seller
+card is hidden in single-seller mode; an ordinary selection calls
+`onSelectSeller`, while a modified click keeps normal browser navigation.
+
+Source is maintained in
+`components/orionplace/products/StorefrontProduct.tsx`; the primary product
+contract is in `interfaces/orionplace/products/IProduct.ts`.
+
+### Props
+
+| Prop                                                                                                              | Meaning                                                                                                              |
+| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `productId: number`                                                                                               | ID of the product handled by StorefrontProduct.                                                                      |
+| `initialProduct?: IProduct`                                                                                       | Server-provided initial product used for the first render and hydration.                                             |
+| `preloaded?: boolean`                                                                                             | Server-loaded record used for the first render and hydration.                                                        |
+| `previewKey?: string`                                                                                             | Preview access key sent only for the requested unpublished product.                                                  |
+| `loadOnMount?: boolean`                                                                                           | Starts the load callback after hydration when server data was not supplied.                                          |
+| `initialError?: string`                                                                                           | Server-provided initial error used for the first render and hydration.                                               |
+| `actionPending?: boolean`                                                                                         | Action currently being submitted.                                                                                    |
+| `actionNotice?: ProductActionNotice`                                                                              | Message shown after the latest action.                                                                               |
+| `needsRefresh?: boolean`                                                                                          | Shows that the surrounding data must be loaded again.                                                                |
+| `profileHref?: string`                                                                                            | Destination used by the profile link.                                                                                |
+| `reviewProps?: Omit<ProductReviewsProps, "productId">`                                                            | Props forwarded to the review child component.                                                                       |
+| `onLoad?: (action: ProductPageLoadAction) => Promise<IProduct \| undefined> \| IProduct \| undefined`             | Called when the component needs its primary data. The callback payload is shown in its type.                         |
+| `onLoaded?: (product: IProduct) => void`                                                                          | Called when the requested data loads successfully. The callback payload is shown in its type.                        |
+| `onMissing?: () => void`                                                                                          | Called when the requested public record does not exist. The callback has no payload.                                 |
+| `onSelectSeller?: (seller: IProductSeller) => void`                                                               | Passes the displayed product’s seller object when the seller is selected. The application opens the seller page. |
+| `onOpenPreorder?: (product: IProduct) => void`                                                                    | Called when the visitor opens the preorder form. The callback payload is shown in its type.                          |
+| `onSubmitPreorder?: (action: ProductPreorderAction) => Promise<boolean \| void> \| boolean \| void`               | Called when the visitor submits the preorder form. The callback payload is shown in its type.                        |
+| `onSignIn?: () => void`                                                                                           | Opens the sign-in page from the preorder dialog when the backend asks the guest to sign in. The callback has no payload. |
+| `onRetryRefresh?: () => Promise<void> \| void`                                                                    | Called when the visitor retries the failed refresh. The callback has no payload.                                     |
+| `onSelectVariant?: (selection: ProductActionSelection & { variant: IProductVariantValue; }) => void`              | Passes the previously displayed product ID in `product` and chosen primary variant in `variant`. An available variant product replaces the card; the application loads missing product data. |
+| `onRequestSecondaryVariants?: (request: IProductSecondaryVariantRequest) => void`                                 | Passes the product ID in `product`, product group ID in `productGroup` and primary variant in `variant` when its secondary variants need loading. The application loads them and supplies them to the product store. |
+| `onSelectSecondaryVariant?: (selection: ProductActionSelection & { variant: IProductSecondaryVariant; }) => void` | Passes the previously displayed product ID in `product` and chosen secondary variant in `variant` after replacing the displayed product. The secondary-variant data remains available. |
+| `onToggleFavorite?: (selection: ProductActionSelection & { selected: boolean; }) => void`                         | Passes the product ID in `product` and desired wishlist state in `selected` after the heart is pressed. The application confirms the change with a request and updates product data. |
+| `onAdd?: (selection: ProductActionSelection & { quantity: number; }) => void`                                     | Passes the product ID in `product` and the requested total quantity in `quantity` when adding an item or changing its quantity. The application sends the request and supplies confirmed product data. |
+| `onRemove?: (selection: ProductActionSelection & { cartItem: number; }) => void`                                  | Passes the product ID in `product` and cart item ID in `cartItem` when removing the last unit. The application removes that cart item and supplies confirmed product data. |
+| `onSubscribe?: (selection: ProductActionSelection) => void`                                                       | Passes the product ID in `product` when an availability notification is requested. The application handles any required sign-in, sends the request and updates subscription state. |
+| `onUnsubscribe?: (selection: ProductActionSelection) => void`                                                     | Passes the product ID in `product` when cancelling an availability notification. The application sends the request and supplies the confirmed subscription state. |
+| `variantProductIds?: number[]`                                                                                    | Product IDs available as variants of the current product.                                                            |
+
+## Русский
+
+`StorefrontProduct` показывает полную страницу товара: путь по категориям,
+галерею, цену и действия покупки, описание, характеристики, сроки возврата,
+производителя, продавца и отзывы.
+
+Для серверного рендера загрузите товар до рендера и передайте его через
+`initialProduct` вместе с `preloaded=true` либо сохраните товар в хранилище
+провайдера и задайте `preloaded=true`. Первоначальный HTML уже содержит
+название, цену и текст описания. После гидратации браузер безопасно возвращает
+поддерживаемое форматирование описания и не отправляет повторный запрос товара.
+
+Если товар не загружен заранее, `loadOnMount` вызывает `onLoad`. Колбэк получает
+`products_search`, `filters.id = productId` и `AbortSignal` запроса. Непустой
+`previewKey` заменяет метод на `products_preview` и добавляет
+`filters.view_key`. Верните найденный `IProduct`. После успешного пустого ответа
+верните `undefined`: компонент вызовет `onMissing`. Ошибка остаётся на странице,
+а «Повторить» отправляет тот же запрос. `onLoaded` получает показанный товар,
+включая загруженный вариант.
+
+Галерея использует полные изображения, а при их отсутствии — малые. Кнопки
+вперёд и назад переходят по кругу. Лента миниатюр прокручивается только тогда,
+когда изображения не помещаются. Клавиши со стрелками выбирают соседнее фото,
+Home и End — первое и последнее. Нажатие, щелчок или Enter на главной
+фотографии открывает фотографии в `ProductReviewImageViewer`; выбранная там
+фотография остаётся на странице. Каждое изображение резервирует место на время
+загрузки.
+
+Локализованное описание товара попадает в серверный HTML как безопасные
+текстовые абзацы, а в браузере получает очищенное форматирование редактора.
+Длинное описание сворачивается за кнопкой «Ещё». Характеристики включают
+производителя, положительный вес, три положительных размера, цифровой тип и
+локализованные группы атрибутов. Единицы берутся из текущего выбора веса и
+длины. Если строки не помещаются в отведённую область,
+`ProductSpecificationsDialog` показывает полный список.
+
+Карточка подробностей передаёт действия корзины, избранного, уведомлений и
+вариантов через `onAdd`, `onRemove`, `onToggleFavorite`, `onSubscribe`,
+`onUnsubscribe`, `onRequestSecondaryVariants`, `onSelectVariant` и
+`onSelectSecondaryVariant`. Когда запрошенный вариант появляется в хранилище
+товаров, страница заменяет название, галерею, описание, характеристики и
+отзывы. `actionPending` и `needsRefresh` блокируют новые действия покупки.
+`actionNotice` показывает результат, а `onRetryRefresh` повторно загружает
+данные после принятого изменения, для которого не удалось получить свежий
+товар.
+
+Выбор предзаказа открывает `ProductPreorderDialog`. `onSubmitPreorder` получает
+точный запрос `preorders_create` с ID товара и очищенными от крайних пробелов
+контактами гостя. Значение `false` оставляет окно открытым. Успешное завершение
+закрывает его, а отклонённый запрос показывает ошибку и разрешает повторить
+отправку. Ошибки полей из `OrionplaceApiError` появляются под полями email и
+телефона. Если бэкенд ответил с кодом `sign_in` (гость указал контакт
+зарегистрированного покупателя), окно показывает кнопку «Войти», которая
+вызывает `onSignIn`.
+
+`reviewProps` передаёт текущие отзывы и типизированные действия в
+`ProductReviews`. Сводка использует `feedback_stat` и переводит к отзывам.
+Физический товар показывает каждый положительный срок возврата; у цифрового
+товара раздел возврата скрыт. Ссылка производителя использует
+`manufacture.id`. В режиме одного продавца карточка продавца скрыта. Обычный
+выбор вызывает `onSelectSeller`, а щелчок с модификатором сохраняет стандартную
+навигацию браузера.
+
+Исходный файл:
+`components/orionplace/products/StorefrontProduct.tsx`; основной контракт
+товара находится в `interfaces/orionplace/products/IProduct.ts`.
+
+### Свойства
+
+| Свойство                                                                                                          | Назначение                                                                                                         |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `productId: number`                                                                                               | ID товара, с которым работает StorefrontProduct.                                                                   |
+| `initialProduct?: IProduct`                                                                                       | Начальное значение товара, полученное на сервере для первого рендера и гидратации.                                 |
+| `preloaded?: boolean`                                                                                             | Запись, загруженная на сервере для первого рендера и гидратации.                                                   |
+| `previewKey?: string`                                                                                             | Ключ предпросмотра только для запрошенного неопубликованного товара.                                               |
+| `loadOnMount?: boolean`                                                                                           | Запускает загрузку после гидратации, если серверные данные не переданы.                                            |
+| `initialError?: string`                                                                                           | Начальное значение ошибки, полученное на сервере для первого рендера и гидратации.                                 |
+| `actionPending?: boolean`                                                                                         | Действие, которое сейчас отправляется.                                                                             |
+| `actionNotice?: ProductActionNotice`                                                                              | Сообщение после последнего действия.                                                                               |
+| `needsRefresh?: boolean`                                                                                          | Показывает, что внешние данные нужно загрузить заново.                                                             |
+| `profileHref?: string`                                                                                            | Адрес ссылки профиля.                                                                                              |
+| `reviewProps?: Omit<ProductReviewsProps, "productId">`                                                            | Свойства, передаваемые дочернему компоненту отзывов.                                                               |
+| `onLoad?: (action: ProductPageLoadAction) => Promise<IProduct \| undefined> \| IProduct \| undefined`             | Вызывается, когда компоненту нужны основные данные. Данные обработчика указаны в его типе.                         |
+| `onLoaded?: (product: IProduct) => void`                                                                          | Вызывается, когда запрошенные данные успешно загружены. Данные обработчика указаны в его типе.                     |
+| `onMissing?: () => void`                                                                                          | Вызывается, когда запрошенная общедоступная запись не существует. Обработчик не получает данные.                   |
+| `onSelectSeller?: (seller: IProductSeller) => void`                                                               | Передаёт объект продавца отображаемого товара при выборе продавца. Приложение открывает его страницу. |
+| `onOpenPreorder?: (product: IProduct) => void`                                                                    | Вызывается, когда покупатель открывает форму предзаказа. Данные обработчика указаны в его типе.                    |
+| `onSubmitPreorder?: (action: ProductPreorderAction) => Promise<boolean \| void> \| boolean \| void`               | Вызывается, когда покупатель отправляет форму предзаказа. Данные обработчика указаны в его типе.                   |
+| `onSignIn?: () => void`                                                                                           | Открывает страницу входа из окна предзаказа, когда бэкенд просит гостя войти. Обработчик не получает данные.        |
+| `onRetryRefresh?: () => Promise<void> \| void`                                                                    | Вызывается, когда покупатель повторяет неудачное обновление. Обработчик не получает данные.                        |
+| `onSelectVariant?: (selection: ProductActionSelection & { variant: IProductVariantValue; }) => void`              | Передаёт ID ранее отображаемого товара в `product` и выбранный основной вариант в `variant`. Доступный товар выбранного варианта заменяет карточку; отсутствующие данные загружает приложение. |
+| `onRequestSecondaryVariants?: (request: IProductSecondaryVariantRequest) => void`                                 | Передаёт ID товара в `product`, ID группы товаров в `productGroup` и основной вариант в `variant`, когда для него нужно загрузить дополнительные варианты. Приложение загружает и передаёт их в хранилище товаров. |
+| `onSelectSecondaryVariant?: (selection: ProductActionSelection & { variant: IProductSecondaryVariant; }) => void` | Передаёт ID ранее отображаемого товара в `product` и выбранный дополнительный вариант в `variant` после замены отображаемого товара. Выбор сохраняет данные дополнительных вариантов. |
+| `onToggleFavorite?: (selection: ProductActionSelection & { selected: boolean; }) => void`                         | Передаёт ID товара в `product` и желаемое состояние избранного в `selected` после нажатия сердца. Приложение подтверждает изменение запросом и обновляет данные товара. |
+| `onAdd?: (selection: ProductActionSelection & { quantity: number; }) => void`                                     | Передаёт `product` — ID товара и `quantity` — запрошенное итоговое количество при добавлении или изменении количества. Приложение выполняет запрос и передаёт подтверждённые данные товара. |
+| `onRemove?: (selection: ProductActionSelection & { cartItem: number; }) => void`                                  | Передаёт ID товара в `product` и ID позиции корзины в `cartItem` при удалении последней единицы. Приложение удаляет эту позицию и передаёт подтверждённые данные товара. |
+| `onSubscribe?: (selection: ProductActionSelection) => void`                                                       | Передаёт ID товара в `product` при выборе уведомления о поступлении. Приложение выполняет вход, если он нужен, отправляет запрос и обновляет состояние подписки. |
+| `onUnsubscribe?: (selection: ProductActionSelection) => void`                                                     | Передаёт ID товара в `product` при отмене уведомления о поступлении. Приложение отправляет запрос и передаёт подтверждённое состояние подписки. |
+| `variantProductIds?: number[]`                                                                                    | ID товаров, доступных как варианты текущего товара.                                                                |