orionplace-react 0.1.0 → 0.2.1

package/templates/components/orionplace/catalog/CatalogRepresentative.README.md

@@ -0,0 +1,68 @@
+# CatalogRepresentative
+
+## English
+
+`CatalogRepresentative` renders one compact `ProductCard` for a category
+highlight. `productId` identifies the product; `collection` selects the ordinary
+or featured Application Load collection and defaults to `products`. If the
+product is absent from that collection, nothing is rendered.
+
+`disabled` blocks product, seller and variant selection. `actionsDisabled`
+blocks favorite and purchase actions while keeping product details available.
+The component forwards the complete product, seller, variant, favorite, cart,
+subscription and preorder callback payloads from its physical product card.
+
+### Props
+
+| Prop                                                                                                              | Meaning                                                                                                              |
+| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `productId: number`                                                                                               | ID of the product handled by CatalogRepresentative.                                                                  |
+| `collection?: OrionplaceProductCollection`                                                                        | Product-store collection used to resolve the supplied product ID.                                                    |
+| `disabled?: boolean`                                                                                              | Disables the component controls and prevents new actions.                                                            |
+| `actionsDisabled?: boolean`                                                                                       | Disables product actions while the surrounding flow is busy.                                                         |
+| `productHref?: (id: number) => string`                                                                            | Builds the product page address; the image and name become links.                                                    |
+| `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. |
+
+## Русский
+
+`CatalogRepresentative` выводит одну компактную `ProductCard` для товара,
+представляющего категорию. `productId` задаёт товар, а `collection` выбирает
+обычную или рекомендованную подборку из Application Load; по умолчанию
+используется `products`. Если в выбранной подборке нет такого товара, компонент
+ничего не выводит.
+
+`disabled` блокирует выбор товара, продавца и варианта. `actionsDisabled`
+блокирует действия с избранным и покупкой, сохраняя доступ к сведениям о товаре.
+Компонент без изменений передаёт данные событий товара, продавца, вариантов,
+избранного, корзины, подписки и предзаказа из физической карточки товара.
+
+### Свойства
+
+| Свойство                                                                                                          | Назначение                                                                                                         |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `productId: number`                                                                                               | ID товара, с которым работает CatalogRepresentative.                                                               |
+| `collection?: OrionplaceProductCollection`                                                                        | Коллекция store товаров, в которой компонент ищет переданный ID товара.                                            |
+| `disabled?: boolean`                                                                                              | Блокирует элементы компонента и новые действия.                                                                    |
+| `actionsDisabled?: boolean`                                                                                       | Блокирует действия с товаром, пока внешний сценарий занят.                                                         |
+| `productHref?: (id: number) => string`                                                                            | Строит адрес страницы товара; фото и название становятся ссылками.                                                 |
+| `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/catalog/CatalogRepresentative.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import {
+  ProductCard,
+  type ProductCardProps,
+} from '@/components/orionplace/products/ProductCard';
+
+type ProductEvents = Pick<
+  ProductCardProps,
+  | 'onSelect'
+  | 'onSelectSeller'
+  | 'onSelectVariant'
+  | 'onRequestSecondaryVariants'
+  | 'onSelectSecondaryVariant'
+  | 'onToggleFavorite'
+  | 'onAdd'
+  | 'onRemove'
+  | 'onSubscribe'
+  | 'onUnsubscribe'
+  | 'onPreorder'
+>;
+
+export interface CatalogRepresentativeProps extends ProductEvents {
+  productId: number;
+  collection?: ProductCardProps['collection'];
+  disabled?: boolean;
+  actionsDisabled?: boolean;
+  productHref?: ProductCardProps['productHref'];
+}
+
+export function CatalogRepresentative({
+  productId,
+  collection = 'products',
+  disabled = false,
+  actionsDisabled = false,
+  productHref,
+  ...events
+}: CatalogRepresentativeProps) {
+  return (
+    <ProductCard
+      productId={productId}
+      collection={collection}
+      disabled={disabled}
+      actionsDisabled={actionsDisabled}
+      dataCatalogProduct={productId}
+      productHref={productHref}
+      compact
+      {...events}
+    />
+  );
+}

package/templates/components/orionplace/catalog/StorefrontCatalog.README.md

@@ -0,0 +1,120 @@
+# StorefrontCatalog · React
+
+## English
+
+Public catalog tree with branch navigation and category-product links.
+
+## Contract and dependencies
+
+The component first uses `initialData.tree` when supplied, or the catalog tree
+from the isolated React catalog store. This makes Application Load categories
+and a server-fetched `catalog_load` response available in guest server HTML.
+Without `initialData`, `onLoad` receives the exact `catalog_load` request and an
+`AbortSignal` after hydration. `loadOnMount` can explicitly enable or suppress
+that request.
+
+A successful load replaces the catalog-store snapshot, returns navigation to
+the root and calls `onDataChange` with the complete response data. An error
+keeps the previous category tree and selected branch visible. Refresh starts a
+new load; unmounting aborts the active request.
+
+Only categories with `is_public = true` are shown. A category name comes from
+its selected-language `locale.cg_name`, with the numeric ID as a fallback. The
+card uses `menu_image`, then `logo_image`; every rendered image reserves a 4:3
+area and physical width and height. A Categories button opens the direct public
+children. All and the branch buttons return to an earlier level. With
+`onOpenBranch` the page keeps the open level (the demo pages keep it in
+`?category=<id>`, so Back goes one level up) and passes it back as `branch`.
+
+The product link defaults to `/category/:id` with the selected locale. A normal
+click calls `onSelectCategory` when that callback is supplied; otherwise the
+link navigates normally. A click with a browser modifier always retains native
+new-tab or new-window behavior. `disabled` blocks refresh, branch and product
+selection.
+
+The All button or the last breadcrumb marks the current level with
+`aria-current="page"`; refresh, breadcrumb and Categories buttons are disabled
+while a load runs. The number of columns follows the width available to the
+catalog, not the window width.
+
+Source is maintained in
+`components/orionplace/catalog/StorefrontCatalog.tsx`; the physical response
+interface is `interfaces/orionplace/catalog/ICatalogDirectory.ts`.
+
+### Props
+
+| Prop                                                                                   | Meaning                                                                                                 |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `initialData?: { tree: ICategory[]; childfree: number[]; unique_ids: number[]; }`      | 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.                             |
+| `disabled?: boolean`                                                                   | Disables the component controls and prevents new actions.                                               |
+| `categoryHref?: (categoryId: number, locale: string) => string`                        | Builds the View products address from the category ID and the store language; default `/category/:id?locale=…`. |
+| `onLoad: (action: StorefrontCatalogLoadAction) => Promise<CatalogData> \| CatalogData` | Called when the component needs its primary data. The callback payload is shown in its type.            |
+| `onSelectCategory?: (category: ICategory) => void`                                     | Called with the category on a normal View products click; the link is then not followed and the application navigates. |
+| `onDataChange?: (data: CatalogData) => void`                                           | Called when the component has a new confirmed data snapshot. The callback payload is shown in its type. |
+| `branch?: number`                                                                      | ID of the open category level when the page keeps it; used together with `onOpenBranch`. |
+| `onOpenBranch?: (categoryId?: number) => void`                                         | Called by Categories, All and the branch buttons with the level to open (no ID: all categories); the component then shows `branch`. |
+
+## Русский
+
+Компонент показывает дерево общедоступных категорий, переходы между его ветками
+и ссылки на товары категории.
+
+Сначала используется `initialData.tree`, а при отсутствии этого свойства —
+дерево из отдельного React store каталога. Поэтому категории из Загрузки
+приложения или серверного ответа `catalog_load` доступны уже в гостевом HTML. Без
+`initialData` после гидратации `onLoad` получает точный запрос `catalog_load` и
+`AbortSignal`. Свойство `loadOnMount` позволяет явно включить или отключить этот
+запрос.
+
+Успешная загрузка заменяет снимок в store каталога, возвращает навигацию к корню
+и вызывает `onDataChange` с полными данными ответа. Ошибка сохраняет прежнее
+дерево и открытую ветку. Кнопка «Обновить» начинает новую загрузку, а
+размонтирование отменяет активный запрос.
+
+Показаны только категории с `is_public = true`. Название берётся из
+`locale.cg_name` для выбранного языка, а при его отсутствии используется
+числовой ID. Карточка сначала использует `menu_image`, затем `logo_image`.
+Каждое показанное изображение резервирует область 4:3 и имеет физические
+`width` и `height`. Кнопка «Категории» открывает прямые общедоступные дочерние
+категории. Кнопки «Все» и текущего пути возвращают на нужный уровень. С
+`onOpenBranch` открытый уровень хранит страница (демо-страницы хранят его в
+`?category=<id>`, поэтому «Назад» поднимается на уровень выше) и передаёт его в
+`branch`.
+
+Ссылка на товары по умолчанию ведёт на `/category/:id` с выбранным языком. При
+обычном щелчке вызывается `onSelectCategory`, если обработчик передан; иначе
+работает обычный переход. Щелчок с модификатором всегда сохраняет стандартное
+открытие в новой вкладке или окне. `disabled` блокирует обновление, переход в
+ветку и выбор товаров.
+
+Кнопка «Все» или последний пункт пути отмечает текущий уровень атрибутом
+`aria-current="page"`; во время загрузки кнопки обновления, пути и «Категории»
+недоступны. Число колонок зависит от ширины, доступной каталогу, а не от
+ширины окна.
+
+Исходный файл:
+`components/orionplace/catalog/StorefrontCatalog.tsx`; физический интерфейс
+ответа: `interfaces/orionplace/catalog/ICatalogDirectory.ts`.
+
+### Свойства
+
+| Свойство                                                                               | Назначение                                                                                                    |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `initialData?: { tree: ICategory[]; childfree: number[]; unique_ids: number[]; }`      | Начальные данные с сервера для первого рендера и гидратации.                                                  |
+| `initialError?: string`                                                                | Начальное значение ошибки, полученное на сервере для первого рендера и гидратации.                            |
+| `loadOnMount?: boolean`                                                                | Запускает загрузку после гидратации, если серверные данные не переданы.                                       |
+| `disabled?: boolean`                                                                   | Блокирует элементы компонента и новые действия.                                                               |
+| `categoryHref?: (categoryId: number, locale: string) => string`                        | Строит адрес кнопки «Открыть товары» по ID категории и языку магазина; по умолчанию `/category/:id?locale=…`. |
+| `onLoad: (action: StorefrontCatalogLoadAction) => Promise<CatalogData> \| CatalogData` | Вызывается, когда компоненту нужны основные данные. Данные обработчика указаны в его типе.                    |
+| `onSelectCategory?: (category: ICategory) => void`                                     | Вызывается с категорией при обычном нажатии «Открыть товары»; ссылка тогда не открывается, переход выполняет приложение. |
+| `onDataChange?: (data: CatalogData) => void`                                           | Вызывается, когда компонент получил новый подтверждённый набор данных. Данные обработчика указаны в его типе. |
+| `branch?: number`                                                                      | ID открытого уровня категорий, если его хранит страница; передаётся вместе с `onOpenBranch`. |
+| `onOpenBranch?: (categoryId?: number) => void`                                         | Вызывается кнопками «Категории», «Все» и кнопками пути с уровнем, который нужно открыть (без ID — все категории); затем компонент показывает `branch`. |
+
+## Category visibility / Видимость категорий
+
+Navigation omits categories with `exclude_from_tree: true` and all their descendants. The full published catalog remains available for product main-category names, links and breadcrumbs.
+
+В навигации скрываются категории с `exclude_from_tree: true` и все их подкатегории. Полный каталог опубликованных категорий сохраняется для названий, ссылок и цепочек основной категории товара.

package/templates/components/orionplace/catalog/StorefrontCatalog.module.css

@@ -0,0 +1,179 @@
+.root {
+  display: flex;
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+  flex-direction: column;
+  gap: 1.25rem;
+  color: var(--orionplace-text);
+  font: inherit;
+  font-size: 0.875rem;
+  line-height: 1.5rem;
+  container-type: inline-size;
+}
+
+.heading {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+}
+
+.heading h1 {
+  margin: 0;
+  font-size: 1.5rem;
+  font-weight: 500;
+  line-height: 1.25;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.trail {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 2.5rem 1rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.grid li {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.grid h2 {
+  margin: 0 0 auto;
+  overflow-wrap: anywhere;
+  font-size: 0.875rem;
+  font-weight: 500;
+  line-height: 1.25rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.image {
+  box-sizing: border-box;
+  width: 100%;
+  height: auto;
+  aspect-ratio: 4 / 3;
+  padding: 1.5rem;
+  object-fit: contain;
+  background: var(--orionplace-surface);
+}
+
+.button {
+  display: inline-flex;
+  box-sizing: border-box;
+  width: fit-content;
+  min-height: 2.75rem;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  padding: 0.5rem 1.25rem;
+  border: 1px solid var(--orionplace-text);
+  border-radius: 0;
+  color: var(--orionplace-text);
+  background: transparent;
+  font: inherit;
+  font-size: 0.75rem;
+  line-height: 1rem;
+  font-weight: 500;
+  text-decoration: none;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  cursor: pointer;
+  outline: none;
+}
+
+.button:focus-visible {
+  background: var(--orionplace-hover);
+}
+
+@media (hover: hover) {
+  .button:hover {
+    background: var(--orionplace-hover);
+  }
+}
+
+.button:disabled,
+.button[aria-disabled='true'] {
+  cursor: default;
+  opacity: 0.6;
+}
+
+/* Category cards stretch both actions to the card width. */
+.grid .button {
+  width: 100%;
+  padding-right: 0.75rem;
+  padding-left: 0.75rem;
+}
+
+.primary,
+.button[aria-current='page'] {
+  border-color: var(--orionplace-accent);
+  color: var(--orionplace-surface);
+  background: var(--orionplace-accent);
+}
+
+.primary:focus-visible {
+  background: var(--orionplace-accent);
+  opacity: 0.85;
+}
+
+@media (hover: hover) {
+  .primary:hover {
+    background: var(--orionplace-accent);
+    opacity: 0.85;
+  }
+}
+
+.error {
+  margin: 0;
+  padding: 0.875rem 1rem;
+  border: 1px solid var(--orionplace-danger);
+  color: var(--orionplace-danger);
+  font-size: 0.875rem;
+  line-height: calc(1.25 / 0.875);
+}
+
+.screenReaderOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* The title follows the component's own width, as in the other packages. */
+@container (min-width: 592px) {
+  .heading h1 {
+    font-size: 1.875rem;
+  }
+}
+
+/* Columns follow the catalog's own width, as in the other packages. */
+@container (min-width: 48rem) {
+  .grid {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+}
+
+@container (min-width: 64rem) {
+  .grid {
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+  }
+}