orionplace-react 0.1.0 → 0.2.1

package/templates/components/orionplace/promo/PromoProducts.README.md

@@ -0,0 +1,133 @@
+# PromoProducts · React
+
+## English
+
+`PromoProducts` shows the products covered by one promo-code offer and the
+offer conditions returned with them. `promoTypeId` is the offer ID stored in a
+promo code's `promo_type.id`; every `onLoad` call receives `products_search`
+with that value in `filters.is_good_for_promo`.
+
+Pass the first server response through `initial` to include the offer,
+breadcrumbs and product cards in the initial HTML. Otherwise `loadOnMount`
+loads it in the browser. The first page replaces the offer and calls
+`onLoaded(promo)`; later pages replace only products and pagination, preserving
+the first page's offer. A first page without `page_data.promo` calls
+`onLoaded(null)` and shows that the offer is no longer running. A present offer
+with no matching products has a separate empty state.
+
+The offer block uses the selected language and currency. It shows the offer
+name, discount and maximum discount (`maximum_discount`), covered sellers,
+categories or products, the minimum order (`minimum_order_amount`: what the covered
+products must cost together; a dollar amount, shown as “$ 544 ≈ 40 256 ₽” in another currency and “$ 544” in dollars), a first-purchase-only rule (`first_order_only`),
+whether already-discounted products qualify, and its start and finish dates.
+`promoCode` names the code in the breadcrumb. When it is empty, the localized
+offer name is used; without either that entry is left out. The other breadcrumb entries link to the profile and its
+promo-code tab.
+
+Every returned product is stored in the isolated product store and rendered
+through `ProductGroup`. `productActionsDisabled` or a pending page request
+disables its controls. The product events have the same separate payloads as
+`StorefrontWishlist`: product and seller objects for selection; product ID and
+variant for main or secondary selection; the secondary lookup request; desired
+wishlist state; cart quantity or cart-item ID; and product ID for subscribe,
+unsubscribe and preorder. `productHref` supplies the product-card links.
+
+Changing `promoTypeId` clears the previous offer and products, cancels the old
+request and loads the new offer. If a later-page request fails, the confirmed
+offer and products remain visible with Retry.
+
+Source is maintained in
+`components/orionplace/promo/PromoProducts.tsx`; the response contract is in
+`interfaces/orionplace/products/IProductSearchApi.ts`.
+
+### Props
+
+| Prop                                                                                                                                                                                                                                                  | Meaning                                                                                                              |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `promoTypeId: number`                                                                                                                                                                                                                                 | ID of the promo type handled by PromoProducts.                                                                       |
+| `promoCode?: string`                                                                                                                                                                                                                                  | Promotion code used to load the matching offer.                                                                      |
+| `initial?: { products?: { data: IProduct[]; rpag: IApiPagination; }; min_max?: IProductSearchRanges; variants?: Record<string, IProductVariantFilter>; selects?: IProductSearchChoices; c_cat_products?: number; promo?: IPromoDefinition \| null; }` | Server-provided initial data used for the first render and hydration.                                                |
+| `initialError?: string`                                                                                                                                                                                                                               | Server-provided initial error used for the first render and hydration.                                               |
+| `loadOnMount?: boolean`                                                                                                                                                                                                                               | Starts the load callback after hydration when server data was not supplied.                                          |
+| `productActionsDisabled?: boolean`                                                                                                                                                                                                                    | Disables cart, wishlist, subscription and preorder actions.                                                          |
+| `productHref?: (id: number) => string`                                                                                                                                                                                                                | Builds the product destination from the callback arguments.                                                          |
+| `onLoad: (action: PromoProductsLoadAction) => Promise<PromoProductsPage> \| PromoProductsPage`                                                                                                                                                        | Called when the component needs its primary data. The callback payload is shown in its type.                         |
+| `onLoaded?: (promo: IPromoDefinition \| null) => void`                                                                                                                                                                                                | Called when the requested data loads successfully. The callback payload is shown in its type.                        |
+| `onPageChange?: (page: number) => void`                                                                                                                                                                                                               | Called when the visitor requests another page. The callback payload is shown in its type.                            |
+| `onSelect?: (product: IProduct) => void`                                                                                                                                                                                                              | Passes the displayed product object when its image or name is selected. The application handles product navigation. |
+| `onSelectSeller?: (seller: IProductSeller) => void`                                                                                                                                                                                                   | Passes the displayed product’s seller object when the seller is selected. The application opens the seller page. |
+| `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. |
+| `onPreorder?: (selection: ProductActionSelection) => void`                                                                                                                                                                                            | Passes the product ID in `product` when preorder is selected. The application collects the required contact details and submits the request. |
+
+## Русский
+
+`PromoProducts` показывает товары, на которые действует предложение промокода,
+и полученные вместе с ними условия. `promoTypeId` — ID предложения из
+`promo_type.id` промокода. Каждый вызов `onLoad` получает метод
+`products_search` с этим значением в `filters.is_good_for_promo`.
+
+Передайте первый серверный ответ через `initial`, чтобы условия, путь и карточки
+товаров вошли в первоначальный HTML. Иначе `loadOnMount` загружает их в
+браузере. Первая страница заменяет предложение и вызывает `onLoaded(promo)`.
+Следующие страницы заменяют только товары и пагинацию, сохраняя предложение с
+первой страницы. Если в первой странице нет `page_data.promo`, компонент
+вызывает `onLoaded(null)` и сообщает, что акция больше не действует. Для
+действующей акции без подходящих товаров показано отдельное пустое состояние.
+
+Блок предложения использует выбранные язык и валюту. В нём видны название,
+скидка и максимальная скидка (`maximum_discount`), подходящие продавцы, категории
+или товары, минимальная сумма заказа (`minimum_order_amount`: сколько должны стоить вместе
+товары, на которые действует код; сумма в долларах: «$ 544 ≈ 40 256 ₽» в другой валюте и «$ 544» в долларах), правило
+«только для первой покупки» (`first_order_only`), возможность применять промокод к товару со скидкой, а
+также даты начала и окончания. `promoCode` задаёт код в пути страницы. Если он пуст, используется
+локализованное название предложения; без кода и известной акции этот элемент не выводится.
+Другие элементы пути ведут в профиль и на вкладку промокодов.
+
+Каждый полученный товар сохраняется в отдельном хранилище товаров и выводится
+через `ProductGroup`. `productActionsDisabled` или выполняемый запрос страницы
+блокирует элементы карточек. События товаров имеют те же отдельные данные, что
+и в `StorefrontWishlist`: товар и продавец для выбора; ID товара и вариант для
+основного или дополнительного выбора; запрос дополнительных вариантов;
+желаемое состояние избранного; количество или ID позиции корзины; ID товара
+для подписки, отписки и предзаказа. `productHref` задаёт ссылки карточек.
+
+Изменение `promoTypeId` очищает прежнее предложение и товары, отменяет старый
+запрос и загружает новую акцию. Если не удалось загрузить следующую страницу,
+подтверждённые условия и товары остаются рядом с кнопкой повтора.
+
+Исходный файл:
+`components/orionplace/promo/PromoProducts.tsx`; контракт ответа находится в
+`interfaces/orionplace/products/IProductSearchApi.ts`.
+
+### Свойства
+
+| Свойство                                                                                                                                                                                                                                              | Назначение                                                                                                         |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `promoTypeId: number`                                                                                                                                                                                                                                 | ID типа промопредложения, с которым работает PromoProducts.                                                        |
+| `promoCode?: string`                                                                                                                                                                                                                                  | Промокод для загрузки соответствующего предложения.                                                                |
+| `initial?: { products?: { data: IProduct[]; rpag: IApiPagination; }; min_max?: IProductSearchRanges; variants?: Record<string, IProductVariantFilter>; selects?: IProductSearchChoices; c_cat_products?: number; promo?: IPromoDefinition \| null; }` | Начальные данные с сервера для первого рендера и гидратации.                                                       |
+| `initialError?: string`                                                                                                                                                                                                                               | Начальное значение ошибки, полученное на сервере для первого рендера и гидратации.                                 |
+| `loadOnMount?: boolean`                                                                                                                                                                                                                               | Запускает загрузку после гидратации, если серверные данные не переданы.                                            |
+| `productActionsDisabled?: boolean`                                                                                                                                                                                                                    | Блокирует корзину, избранное, подписку и предзаказ.                                                                |
+| `productHref?: (id: number) => string`                                                                                                                                                                                                                | Строит адрес ссылки товара из аргументов обработчика.                                                              |
+| `onLoad: (action: PromoProductsLoadAction) => Promise<PromoProductsPage> \| PromoProductsPage`                                                                                                                                                        | Вызывается, когда компоненту нужны основные данные. Данные обработчика указаны в его типе.                         |
+| `onLoaded?: (promo: IPromoDefinition \| null) => void`                                                                                                                                                                                                | Вызывается, когда запрошенные данные успешно загружены. Данные обработчика указаны в его типе.                     |
+| `onPageChange?: (page: number) => void`                                                                                                                                                                                                               | Вызывается, когда покупатель открывает другую страницу. Данные обработчика указаны в его типе.                     |
+| `onSelect?: (product: IProduct) => void`                                                                                                                                                                                                              | Передаёт объект отображаемого товара при выборе его изображения или названия. Приложение выполняет переход к товару. |
+| `onSelectSeller?: (seller: IProductSeller) => 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` при отмене уведомления о поступлении. Приложение отправляет запрос и передаёт подтверждённое состояние подписки. |
+| `onPreorder?: (selection: ProductActionSelection) => void`                                                                                                                                                                                            | Передаёт ID товара в `product` при выборе предзаказа. Приложение собирает необходимые контактные данные и отправляет запрос. |

package/templates/components/orionplace/promo/PromoProducts.module.css

@@ -0,0 +1,68 @@
+.root {
+  composes: feature featureStack account from '../account/account.module.css';
+  width: 100%;
+  container-type: inline-size;
+}
+
+.title {
+  composes: featureTitle from '../account/account.module.css';
+}
+
+/* The offer is one card of the account entry list, as in the other
+   packages. */
+.offers {
+  composes: entryList from '../account/account.module.css';
+}
+
+.offer {
+  composes: entry from '../account/account.module.css';
+}
+
+.offerHead {
+  composes: entryHead from '../account/account.module.css';
+}
+
+.offerName {
+  composes: entryTitle from '../account/account.module.css';
+}
+
+.icon {
+  composes: entryIcon from '../account/account.module.css';
+}
+
+.facts {
+  composes: entryFacts from '../account/account.module.css';
+}
+
+.fact {
+  composes: entryFact from '../account/account.module.css';
+}
+
+.term {
+  composes: entryTerm from '../account/account.module.css';
+}
+
+.value {
+  composes: entryValue from '../account/account.module.css';
+}
+
+.hint {
+  composes: featureCopy featureMuted from '../account/account.module.css';
+}
+
+.error {
+  composes: notice noticeError from '../account/account.module.css';
+}
+
+.button {
+  composes: featureButton from '../account/account.module.css';
+}
+
+.screenReaderOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}

package/templates/components/orionplace/promo/PromoProducts.tsx

@@ -0,0 +1,345 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import {
+  useOrionplaceProductsStore,
+  useOrionplaceSelections,
+} from '@/providers/OrionplaceProvider';
+import type { IApiPagination } from '@/interfaces/orionplace/accounts/IProfileData';
+import type { IPromoDefinition } from '@/interfaces/orionplace/cart/ICartData';
+import type { IProduct } from '@/interfaces/orionplace/products/IProduct';
+import type {
+  IProductSearchRequest,
+  IProductSearchResponse,
+} from '@/interfaces/orionplace/products/IProductSearchApi';
+import type { IBreadcrumb } from '@/interfaces/orionplace/shared/IBreadcrumb';
+import { accountLabels } from '@/lib/orionplace/accountLabels';
+import { featureLabels } from '@/lib/orionplace/featureLabels';
+import { mergePagination } from '@/lib/orionplace/featureData';
+import { promoLabels } from '@/lib/orionplace/promoLabels';
+import {
+  promoIconPaths,
+  promoName,
+  promoOfferConditions,
+} from '@/lib/orionplace/promoPresentation';
+import {
+  ProductGroup,
+  type ProductGroupEvents,
+  type ProductGroupProps,
+} from '@/components/orionplace/products/ProductGroup';
+import { OrionplaceBreadcrumbs } from '@/components/orionplace/shared/OrionplaceBreadcrumbs';
+import { OrionplaceEmptyState } from '@/components/orionplace/shared/OrionplaceEmptyState';
+import { StorefrontPagination } from '@/components/orionplace/shared/StorefrontPagination';
+import styles from './PromoProducts.module.css';
+import { apiErrorMessage } from '@/lib/orionplace/api';
+
+type PromoProductsPage = NonNullable<IProductSearchResponse['page_data']>;
+
+export interface PromoProductsLoadAction {
+  endpoint: 'products_search';
+  request: IProductSearchRequest & {
+    filters: { is_good_for_promo: number };
+  };
+  signal: AbortSignal;
+}
+
+export interface PromoProductsProps extends ProductGroupEvents {
+  promoTypeId: number;
+  promoCode?: string;
+  initial?: PromoProductsPage;
+  initialError?: string;
+  loadOnMount?: boolean;
+  productActionsDisabled?: boolean;
+  productHref?: ProductGroupProps['productHref'];
+  onLoad: (
+    action: PromoProductsLoadAction,
+  ) => Promise<PromoProductsPage> | PromoProductsPage;
+  onLoaded?: (promo: IPromoDefinition | null) => void;
+  onPageChange?: (page: number) => void;
+}
+
+function PromoIcon({ path }: { path: string }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className={styles.icon}
+    >
+      <path d={path} />
+    </svg>
+  );
+}
+
+export function PromoProducts({
+  promoTypeId,
+  promoCode = '',
+  initial,
+  initialError = '',
+  loadOnMount = true,
+  productActionsDisabled = false,
+  productHref,
+  onLoad,
+  onLoaded,
+  onPageChange,
+  ...events
+}: PromoProductsProps) {
+  const locale                      = useOrionplaceSelections((state) => state.localeCode);
+  const currencyId                  = useOrionplaceSelections((state) => state.currencyId);
+  const currencies                  = useOrionplaceSelections(
+    (state) => state.init?.currencies,
+  );
+  const currency                    = currencies?.[currencyId];
+  const productStore                = useOrionplaceProductsStore();
+  const common                      = featureLabels(locale);
+  const copy                        = promoLabels(locale);
+  const account                     = accountLabels(locale);
+  const [promo, setPromo]           = useState<IPromoDefinition | null>(
+    initial?.promo ?? null,
+  );
+  const [products, setProducts]     = useState<IProduct[]>(
+    initial?.products?.data ?? [],
+  );
+  const [pagination, setPagination] = useState<Partial<IApiPagination>>(
+    initial?.products?.rpag ?? {},
+  );
+  const [loaded, setLoaded]         = useState(Boolean(initial));
+  const [pending, setPending]       = useState(
+    loadOnMount && !initial && !initialError,
+  );
+  const [error, setError]           = useState(initialError);
+  const activeRequest               = useRef<AbortController | undefined>(undefined);
+  const requested                   = useRef(false);
+  const previousPromo               = useRef(promoTypeId);
+  const callbacks                   = useRef({ onLoad, onLoaded });
+  callbacks.current                 = { onLoad, onLoaded };
+
+  const conditions                  = promoOfferConditions(
+    promo,
+    locale,
+    currencyId,
+    currency,
+    copy,
+    currencies,
+  );
+  // The code has no page of its own; an address without a code or a known
+  // offer has no entry to name.
+  const breadcrumbs: IBreadcrumb[]  = [
+    {
+      id: 'profile',
+      label: account.profile,
+      to: { path: '/profile', query: { locale } },
+    },
+    {
+      id: 'promocodes',
+      label: copy.crumbPromocodes,
+      to: {
+        path: '/promocodes',
+        query: { locale },
+      },
+    },
+    {
+      id: 'code',
+      label: promoCode || promoName(promo, locale),
+    },
+    { id: 'products', label: copy.crumbProducts },
+  ].filter((crumb) => crumb.label);
+
+  async function fetchPage(controller: AbortController, page: number) {
+    const data         = await callbacks.current.onLoad({
+      endpoint: 'products_search',
+      request: {
+        filters: { is_good_for_promo: promoTypeId },
+        paginate: { page, pp_items: 12 },
+      },
+      signal: controller.signal,
+    });
+    if (controller.signal.aborted) {
+      return;
+    }
+
+    if (page === 1) {
+      const offer = data.promo ?? null;
+      setPromo(offer);
+      callbacks.current.onLoaded?.(offer);
+    }
+    const nextProducts = data.products?.data ?? [];
+    for (const product of nextProducts) {
+      productStore
+        .getState()
+        .setProduct(product, 'products', data.selects?.sellers);
+    }
+    setProducts(nextProducts);
+    setPagination((previous) =>
+      mergePagination(page === 1 ? {} : previous, data.products?.rpag),
+    );
+    setLoaded(true);
+  }
+
+  async function load(page = 1) {
+    if (activeRequest.current) {
+      return;
+    }
+    const controller      = new AbortController();
+    activeRequest.current = controller;
+    setPending(true);
+    setError('');
+    try {
+      await fetchPage(controller, page);
+    } catch (reason) {
+      if (!controller.signal.aborted) {
+        setError(
+          apiErrorMessage(reason) || common.failed,
+        );
+      }
+    } finally {
+      if (activeRequest.current === controller) {
+        activeRequest.current = undefined;
+        setPending(false);
+      }
+    }
+  }
+
+  function changePage(page: number) {
+    onPageChange?.(page);
+    void load(page);
+  }
+
+  useEffect(() => {
+    for (const product of initial?.products?.data ?? []) {
+      productStore
+        .getState()
+        .setProduct(product, 'products', initial?.selects?.sellers);
+    }
+    if (initial) {
+      callbacks.current.onLoaded?.(initial.promo ?? null);
+    }
+  }, [initial, productStore]);
+
+  useEffect(() => {
+    if (!requested.current && loadOnMount && !initial && !initialError) {
+      requested.current = true;
+      void load();
+    }
+    return () => {
+      activeRequest.current?.abort();
+      activeRequest.current = undefined;
+      requested.current     = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    if (previousPromo.current === promoTypeId) {
+      return;
+    }
+    previousPromo.current = promoTypeId;
+    activeRequest.current?.abort();
+    activeRequest.current = undefined;
+    setPending(false);
+    setPromo(null);
+    setProducts([]);
+    setPagination({});
+    setLoaded(false);
+    setError('');
+    if (loadOnMount) {
+      void load();
+    }
+  }, [promoTypeId]);
+
+  return (
+    <section
+      className={styles.root}
+      data-feature-part="PromoProducts"
+      aria-busy={pending || undefined}
+    >
+      <OrionplaceBreadcrumbs
+        items={breadcrumbs}
+        loading={pending && !loaded}
+      />
+      <h1 className={styles.title}>{copy.products}</h1>
+
+      {promo ? (
+        <>
+          <div className={styles.offers}>
+            <div
+              className={styles.offer}
+              data-promo-offer
+            >
+              <div className={styles.offerHead}>
+                <PromoIcon path={promoIconPaths.ticket} />
+                <span className={styles.offerName}>{promoName(promo, locale)}</span>
+              </div>
+              <dl className={styles.facts}>
+                {conditions.map((condition) => (
+                  <div
+                    key={condition.key}
+                    className={styles.fact}
+                    data-promo-condition={condition.key}
+                  >
+                    <PromoIcon path={promoIconPaths[condition.icon]} />
+                    <dt className={styles.term}>{condition.label}</dt>
+                    <dd className={styles.value}>{condition.value}</dd>
+                  </div>
+                ))}
+              </dl>
+            </div>
+          </div>
+          <p className={styles.hint}>{copy.productsHint}</p>
+        </>
+      ) : null}
+
+      {error ? (
+        <div
+          role="alert"
+          className={styles.error}
+        >
+          <span>{error}</span>
+          <button
+            type="button"
+            className={styles.button}
+            disabled={pending}
+            onClick={() => void load()}
+          >
+            {common.retry}
+          </button>
+        </div>
+      ) : null}
+      {pending ? (
+        <p
+          role="status"
+          className="op-feature-loading"
+        >
+          <span className={styles.screenReaderOnly}>{common.loading}</span>
+        </p>
+      ) : null}
+
+      {products.length ? (
+        <div data-promo-products>
+          <ProductGroup
+            products={products}
+            productIds={products.map((product) => product.id)}
+            layout="grid"
+            disabled={productActionsDisabled || pending}
+            productHref={productHref}
+            {...events}
+          />
+        </div>
+      ) : loaded && !pending ? (
+        <OrionplaceEmptyState
+          kind="promocodes"
+          message={promo ? copy.productsEmpty : copy.productsMissing}
+        />
+      ) : null}
+
+      <StorefrontPagination
+        pagination={pagination}
+        pending={pending}
+        onChange={changePage}
+      />
+    </section>
+  );
+}

package/templates/components/orionplace/search/MainSearch.README.md

@@ -0,0 +1,73 @@
+# MainSearch
+
+## English
+
+`MainSearch` edits the shared `searchQuery` in the browse store. On `/browse`,
+an initially empty store adopts the trimmed `q` query parameter after the first
+render while showing that same value in the server-rendered input. Search hints
+come from `init.search_hints`; the selected locale is used first and duplicate
+captions are removed. `history` adds the signed-in customer's matching saved
+queries. Focusing or editing the field calls `onHistorySearch` after a short
+pause. Choosing a saved query calls `onSearch`; its remove button passes the
+record ID to `onHistoryDelete`. `historyPending` announces that saved queries
+are loading. `historyError` displays a failed history request. `historyDeleting`
+keeps each affected remove button disabled until its request finishes.
+
+Submitting a non-empty value trims its outer whitespace and calls `onSearch`
+with the resulting text. The component does not navigate or send an API request.
+`disabled` blocks editing and submission. `label` supplies the input placeholder
+and accessible name; `buttonLabel` names the submit control. The storefront
+connects these callbacks to `profile_query_search`, `profile_search_update` and
+`profile_search_delete`; the component keeps transport and navigation in the
+application.
+
+### Props
+
+| Prop                                         | Meaning                                                                                                                                            |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label?: string`                             | Placeholder and accessible name of the search field.                                                                                               |
+| `buttonLabel?: string`                       | Accessible name of the submit button.                                                                                                              |
+| `disabled?: boolean`                         | Blocks editing, submission and saved-query actions.                                                                                                |
+| `history?: readonly MainSearchHistoryItem[]` | Saved searches shown while the field has focus. Each entry contains its ID in `id` and query in `q`.                                               |
+| `historyPending?: boolean`                   | Replaces the saved-query list with a loading message.                                                                                              |
+| `historyError?: string`                      | Message for a failed history request. An empty string hides the message.                                                                           |
+| `historyDeleting?: readonly number[]`        | IDs of entries awaiting a deletion response. Their remove buttons stay disabled.                                                                   |
+| `onSearch?: (query: string) => void`         | Passes nonempty search text with surrounding whitespace removed on form submission, or the selected history entry’s text. The history list closes before the callback. |
+| `onHistorySearch?: (query: string) => void`  | Receives the trimmed field text after focus or editing. An empty string requests the most recent saved searches. The application loads and supplies `history`. |
+| `onHistoryDelete?: (id: number) => void`     | Passes the entry ID when its remove button is pressed. The application removes the entry and supplies updated history. |
+
+## Русский
+
+`MainSearch` редактирует общее поле `searchQuery` в хранилище просмотра. На
+странице `/browse` пустое хранилище принимает очищенный от внешних пробелов
+параметр `q` после первого отображения, а то же значение сразу показывается в
+серверном HTML поля. Подсказки берутся из `init.search_hints`: сначала выбирается
+текст для текущего языка, повторяющиеся подписи удаляются. `history` добавляет
+подходящие сохранённые запросы вошедшего покупателя. При фокусе или изменении
+поля после короткой паузы вызывается `onHistorySearch`. Выбор сохранённого
+запроса вызывает `onSearch`, а кнопка удаления передаёт ID записи в
+`onHistoryDelete`. `historyPending` сообщает о загрузке истории. `historyError`
+показывает ошибку запроса истории, а `historyDeleting` блокирует кнопку удаления
+соответствующей записи до ответа.
+
+При отправке непустого значения компонент удаляет внешние пробелы и вызывает
+`onSearch` с полученным текстом. Компонент сам не переходит на другую страницу и
+не отправляет API-запрос. `disabled` блокирует ввод и отправку. `label` задаёт
+подсказку и доступное имя поля, а `buttonLabel` — имя кнопки отправки. Магазин
+связывает эти обработчики с `profile_query_search`, `profile_search_update` и
+`profile_search_delete`; переход и отправка запросов остаются в приложении.
+
+### Свойства
+
+| Свойство                                     | Назначение                                                                                                                                        |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label?: string`                             | Подсказка и доступное имя поля поиска.                                                                                                            |
+| `buttonLabel?: string`                       | Доступное имя кнопки отправки.                                                                                                                    |
+| `disabled?: boolean`                         | Блокирует ввод, отправку и действия с сохранёнными запросами.                                                                                     |
+| `history?: readonly MainSearchHistoryItem[]` | Сохранённые запросы, показанные при фокусе в поле. `id` содержит ID записи, `q` — запрос.                                                         |
+| `historyPending?: boolean`                   | Заменяет список сохранённых запросов сообщением о загрузке.                                                                                       |
+| `historyError?: string`                      | Сообщение об ошибке запроса истории. Пустая строка скрывает сообщение.                                                                            |
+| `historyDeleting?: readonly number[]`        | ID записей, удаление которых ожидает ответа. Их кнопки удаления недоступны.                                                                       |
+| `onSearch?: (query: string) => void`         | Передаёт непустой поисковый текст без пробелов по краям при отправке формы или текст выбранной записи истории. Перед вызовом список истории закрывается. |
+| `onHistorySearch?: (query: string) => void`  | Получает текст поля без пробелов по краям при фокусе или вводе. Пустая строка запрашивает последние сохранённые запросы. Приложение загружает и передаёт `history`. |
+| `onHistoryDelete?: (id: number) => void`     | Передаёт ID записи при нажатии её кнопки удаления. Приложение удаляет запись и передаёт обновлённую историю. |