orionplace-react 0.7.8 → 0.8.0

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

@@ -1,117 +0,0 @@
-'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

@@ -1,200 +0,0 @@
-# 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 товаров, доступных как варианты текущего товара.                                                                |