orionplace-react 0.1.0 → 0.2.1

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

@@ -0,0 +1,350 @@
+'use client';
+
+import { forwardRef, useEffect, useImperativeHandle, useState } from 'react';
+import type { CSSProperties } from 'react';
+import { useOrionplaceProduct } from '@/hooks/useOrionplaceProduct';
+import {
+  useOrionplaceProducts,
+  useOrionplaceProductsStore,
+  useOrionplaceSelections,
+} from '@/providers/OrionplaceProvider';
+import type {
+  IProductSecondaryVariant,
+  IProductSecondaryVariantValue,
+  IProductVariantValue,
+} from '@/interfaces/orionplace/products/IProduct';
+import type { IProductSecondaryVariantRequest } from '@/interfaces/orionplace/products/IProductSecondaryVariantRequest';
+import type { OrionplaceProductCollection } from '@/stores/orionplaceProducts';
+import { getAvailableValueFromObject } from '@/lib/orionplace/presentation';
+import { productLabels } from '@/lib/orionplace/productLabels';
+import { ProductSecondaryVariantModal } from './ProductSecondaryVariantModal';
+import type { ProductActionSelection } from './ProductCardActions';
+import styles from './ProductCardVariants.module.css';
+
+export interface ProductCardVariantsHandle {
+  openForPurchase: () => void;
+}
+
+export interface ProductCardVariantsProps {
+  productId: number;
+  collection?: OrionplaceProductCollection;
+  variantProductIds?: number[];
+  disabled?: boolean;
+  actionsDisabled?: boolean;
+  onSelect?: (variant: IProductVariantValue) => void;
+  onSelectSecondary?: (variant: IProductSecondaryVariant) => void;
+  onRequestSecondary?: (request: IProductSecondaryVariantRequest) => void;
+  onAdd?: (selection: ProductActionSelection & { quantity: number }) => void;
+  onRemove?: (selection: ProductActionSelection & { cartItem: number }) => void;
+  onSubscribe?: (selection: ProductActionSelection) => void;
+  onUnsubscribe?: (selection: ProductActionSelection) => void;
+  onPreorder?: (selection: ProductActionSelection) => void;
+  className?: string;
+}
+
+export const ProductCardVariants = forwardRef<
+  ProductCardVariantsHandle,
+  ProductCardVariantsProps
+>(function ProductCardVariants(
+  {
+    productId,
+    collection = 'products',
+    variantProductIds,
+    disabled = false,
+    actionsDisabled = false,
+    onSelect,
+    onSelectSecondary,
+    onRequestSecondary,
+    onAdd,
+    onRemove,
+    onSubscribe,
+    onUnsubscribe,
+    onPreorder,
+    className = '',
+  },
+  ref,
+) {
+  const product                         = useOrionplaceProduct(productId, collection);
+  const productsStore                   = useOrionplaceProductsStore();
+  const secondaryStates                 = useOrionplaceProducts(
+    (state) => state.secondaryVariants,
+  );
+  const localeCode                      = useOrionplaceSelections((state) => state.localeCode);
+  const [modalVariant, setModalVariant] = useState<IProductVariantValue>();
+  const [purchaseMode, setPurchaseMode] = useState(false);
+  const primary                         = product?.variants.main_variant;
+  const secondary                       = product?.secondary_variants;
+  const requiresSecondary               =
+    !variantProductIds &&
+    Boolean(primary?.second_exists || secondary?.variants.length);
+  const copy                            = productLabels(localeCode);
+  const primaryName                     =
+    getAvailableValueFromObject(primary?.locale, localeCode) || copy.variants;
+  const secondaryName                   =
+    getAvailableValueFromObject(secondary?.secondary.locale, localeCode) ||
+    copy.secondary;
+
+  useEffect(() => {
+    setModalVariant(undefined);
+  }, [productId, collection]);
+
+  useEffect(() => {
+    if (disabled) {
+      setModalVariant(undefined);
+    }
+  }, [disabled]);
+
+  function offered(id: number | null | undefined) {
+    return (
+      validId(id) &&
+      (!variantProductIds || variantProductIds.includes(Number(id)))
+    );
+  }
+
+  function canSelectPrimary(value: IProductVariantValue) {
+    return (
+      offered(value.reload_product) &&
+      (!requiresSecondary ||
+        (validId(value.id) && validId(product?.product_group_id)))
+    );
+  }
+
+  function isPrimarySelected(value: IProductVariantValue) {
+    const state =
+      product && secondaryStates[`${product.product_group_id}:${value.id}`];
+    return (
+      value.reload_product === productId ||
+      Boolean(
+        state?.data?.variants.some((option) => option.product.id === productId),
+      )
+    );
+  }
+
+  function variantName(
+    value: IProductVariantValue | IProductSecondaryVariantValue,
+  ) {
+    return (
+      getAvailableValueFromObject(value.locale, localeCode) || String(value.id)
+    );
+  }
+
+  function requestSecondary(value: IProductVariantValue) {
+    if (product) {
+      onRequestSecondary?.({
+        product: product.id,
+        productGroup: product.product_group_id,
+        variant: value,
+      });
+    }
+  }
+
+  function openSecondary(value: IProductVariantValue) {
+    if (!product || disabled || !canSelectPrimary(value)) {
+      return;
+    }
+    setModalVariant(value);
+    const state           = productsStore
+      .getState()
+      .getSecondaryVariants(product.product_group_id, value.id);
+    if (state?.status === 'ready' || state?.status === 'loading') {
+      return;
+    }
+    const otherCollection = collection === 'products' ? 'featured' : 'products';
+    const target          =
+      productsStore
+        .getState()
+        .getProduct(Number(value.reload_product), collection) ??
+      productsStore
+        .getState()
+        .getProduct(Number(value.reload_product), otherCollection);
+    if (target?.secondary_variants) {
+      productsStore
+        .getState()
+        .setSecondaryVariants(product.product_group_id, value.id, {
+          status: 'ready',
+          data: target.secondary_variants,
+        });
+      return;
+    }
+    requestSecondary(value);
+  }
+
+  useImperativeHandle(ref, () => ({
+    openForPurchase() {
+      if (disabled || actionsDisabled) {
+        return;
+      }
+      const value =
+        primary?.value.find(isPrimarySelected) ??
+        primary?.value.find(canSelectPrimary);
+      if (value) {
+        openSecondary(value);
+        setPurchaseMode(true);
+      }
+    },
+  }));
+
+  function selectPrimary(value: IProductVariantValue) {
+    if (disabled || !canSelectPrimary(value)) {
+      return;
+    }
+    setPurchaseMode(false);
+    if (requiresSecondary) {
+      openSecondary(value);
+    } else {
+      onSelect?.(value);
+    }
+  }
+
+  function selectModalSecondary(value: IProductSecondaryVariant) {
+    const state  =
+      product &&
+      modalVariant &&
+      productsStore
+        .getState()
+        .getSecondaryVariants(product.product_group_id, modalVariant.id);
+    if (
+      disabled ||
+      !offered(value.product.id) ||
+      state?.status !== 'ready' ||
+      !state.data?.variants.includes(value)
+    ) {
+      return;
+    }
+    const target =
+      productsStore.getState().updates[collection][value.product.id] ??
+      value.product;
+    productsStore.getState().setProduct(
+      {
+        ...target,
+        secondary_variants: state.data,
+      },
+      collection,
+    );
+    setModalVariant(undefined);
+    onSelectSecondary?.(value);
+  }
+
+  if (!primary?.value.length && !secondary?.variants.length) {
+    return null;
+  }
+
+  return (
+    <div
+      className={`${styles.variants} ${className}`.trim()}
+      data-product-part="ProductCardVariants"
+      data-product-variants
+    >
+      {Boolean(primary?.value.length) && (
+        <div
+          role="group"
+          aria-label={primaryName}
+          className={styles.group}
+        >
+          <p className={styles.screenReaderOnly}>{primaryName}</p>
+          <div className={styles.choices}>
+            {primary!.value.map((value) => {
+              const selected = isPrimarySelected(value);
+              const swatch   = Boolean(primary!.is_color && value.color);
+              return (
+                <button
+                  key={value.id}
+                  type="button"
+                  disabled={disabled || !canSelectPrimary(value)}
+                  aria-pressed={selected}
+                  title={`${primaryName}: ${variantName(value)}`}
+                  className={`${styles.choice} ${swatch ? styles.swatch : ''}`}
+                  style={
+                    swatch ? swatchStyle(value.color, selected) : undefined
+                  }
+                  data-product-variant={value.id}
+                  onClick={() => selectPrimary(value)}
+                >
+                  <span
+                    className={swatch ? styles.screenReaderOnly : undefined}
+                  >
+                    {variantName(value)}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      )}
+      {Boolean(secondary?.variants.length) && (
+        <div
+          role="group"
+          aria-label={secondaryName}
+          className={styles.group}
+        >
+          <p className={styles.screenReaderOnly}>{secondaryName}</p>
+          <div className={styles.choices}>
+            {secondary!.variants.map((entry) => {
+              const selected = entry.product.id === productId;
+              const swatch   = Boolean(
+                secondary!.secondary.is_color && entry.value.color,
+              );
+              return (
+                <button
+                  key={entry.product.id}
+                  type="button"
+                  disabled={disabled || !offered(entry.product.id)}
+                  aria-pressed={selected}
+                  title={`${secondaryName}: ${variantName(entry.value)}`}
+                  className={`${styles.choice} ${swatch ? styles.swatch : ''}`}
+                  style={
+                    swatch
+                      ? swatchStyle(entry.value.color, selected)
+                      : undefined
+                  }
+                  data-secondary-variant={entry.product.id}
+                  onClick={() => onSelectSecondary?.(entry)}
+                >
+                  <span
+                    className={swatch ? styles.screenReaderOnly : undefined}
+                  >
+                    {variantName(entry.value)}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      )}
+      {modalVariant && (
+        <ProductSecondaryVariantModal
+          productId={productId}
+          collection={collection}
+          variantId={modalVariant.id}
+          purchaseMode={purchaseMode}
+          actionsDisabled={disabled || actionsDisabled}
+          onAdd={onAdd}
+          onRemove={onRemove}
+          onSubscribe={onSubscribe}
+          onUnsubscribe={onUnsubscribe}
+          onPreorder={onPreorder}
+          onChangePrimary={openSecondary}
+          onRetry={() => requestSecondary(modalVariant)}
+          onSelect={selectModalSecondary}
+          onClose={() => setModalVariant(undefined)}
+        />
+      )}
+    </div>
+  );
+});
+
+function validId(value: number | null | undefined) {
+  return Number.isInteger(value) && Number(value) > 0;
+}
+
+function swatchStyle(
+  color: string | null | undefined,
+  selected: boolean,
+): CSSProperties {
+  return {
+    borderColor: color || undefined,
+    backgroundColor: selected
+      ? 'var(--orionplace-surface)'
+      : color || undefined,
+  };
+}

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

@@ -0,0 +1,89 @@
+# ProductGroup
+
+## English
+
+Renders products from the selected `collection` (`products` by default or
+`featured`) as a responsive group of `ProductCard` instances. `productIds`
+selects and orders specific products. A positive `limit` displays only the
+first matching products. `disabled` prevents card actions. `layout="grid"`
+keeps the grid on narrow screens; the default responsive layout scrolls
+horizontally there. `products` supplies complete product objects when a parent
+request returns a collection that is not part of Application Load. When
+Application Load enables mobile arrows, they appear only if the row can
+scroll. The group forwards each card's selection,
+seller, variant, wishlist and purchase callbacks. `renderFooter` receives
+the product listed in this group, even after its card displays a selected
+variant.
+
+Each card initially includes only its primary image. Hovering or focusing
+one card adds secondary images for that card; other cards keep their first
+image until interacted with.
+
+### Props
+
+| Prop                                                                                                              | Meaning                                                                                                              |
+| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `collection?: OrionplaceProductCollection`                                                                        | Product-store collection used to resolve the supplied product ID.                                                    |
+| `disabled?: boolean`                                                                                              | Disables the component controls and prevents new actions.                                                            |
+| `limit?: number`                                                                                                  | Limits how many supplied entries the component renders.                                                              |
+| `products?: readonly IProduct[]`                                                                                  | Product records supplied for server rendering and hydration.                                                         |
+| `productIds?: number[]`                                                                                           | Product IDs rendered in the supplied order.                                                                          |
+| `layout?: "responsive" \| "grid"`                                                                                 | Selects the supported component layout.                                                                              |
+| `productHref?: (id: number) => string`                                                                            | Builds the product destination from the callback arguments.                                                          |
+| `renderFooter?: (product: IProduct) => ReactNode`                                                                 | Replaces the default footer region; the renderer inputs are shown in its type.                                       |
+| `className?: string`                                                                                              | Additional CSS class for the component root.                                                                         |
+| `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. |
+
+## Русский
+
+Показывает товары из `collection` (`products` по умолчанию или `featured`)
+группой карточек `ProductCard`. `productIds` выбирает товары и задаёт их
+порядок. Положительное значение `limit` оставляет первые подходящие товары.
+`disabled` запрещает действия с карточками. `layout="grid"` сохраняет сетку
+на узком экране; обычный режим там прокручивается по горизонтали. `products`
+передаёт полные объекты товаров, если родительский запрос вернул подборку,
+которой нет в Application Load. Если настройка Application Load разрешает
+мобильные стрелки, они появляются,
+когда товары можно прокрутить. Группа передаёт обработчикам выбор товара,
+продавца, варианта, избранного и действия покупки. `renderFooter` получает
+товар из списка группы, даже если карточка показывает выбранный вариант.
+
+Изначально каждая карточка содержит только первую фотографию. После
+наведения или перехода к карточке с клавиатуры остальные фотографии
+появляются у этой карточки; другие карточки продолжают показывать только
+первую фотографию.
+
+### Свойства
+
+| Свойство                                                                                                          | Назначение                                                                                                         |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `collection?: OrionplaceProductCollection`                                                                        | Коллекция store товаров, в которой компонент ищет переданный ID товара.                                            |
+| `disabled?: boolean`                                                                                              | Блокирует элементы компонента и новые действия.                                                                    |
+| `limit?: number`                                                                                                  | Ограничивает число показанных переданных записей.                                                                  |
+| `products?: readonly IProduct[]`                                                                                  | Товары для серверного рендера и гидратации.                                                                        |
+| `productIds?: number[]`                                                                                           | ID для товара, используемые в переданном порядке.                                                                  |
+| `layout?: "responsive" \| "grid"`                                                                                 | Выбирает поддерживаемый вариант компоновки.                                                                        |
+| `productHref?: (id: number) => string`                                                                            | Строит адрес ссылки товара из аргументов обработчика.                                                              |
+| `renderFooter?: (product: IProduct) => ReactNode`                                                                 | Заменяет стандартный блок нижней части; входные данные функции указаны в её типе.                                  |
+| `className?: string`                                                                                              | Дополнительный CSS-класс корневого элемента.                                                                       |
+| `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/products/ProductGroup.module.css

@@ -0,0 +1,64 @@
+.group { min-width: 0; container: products / inline-size; }
+.track {
+  position: relative;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  align-items: stretch;
+  column-gap: 16px;
+  row-gap: 0;
+}
+.track > [data-product-layout='card'] {
+  grid-row: span 8;
+  grid-template-rows: subgrid;
+  align-content: normal;
+  max-width: none;
+  padding-bottom: 32px;
+}
+.track [data-product-part='ProductCardDescription'] { display: none; }
+.scrollControls { display: flex; justify-content: end; gap: 8px; margin-top: 4px; }
+.scrollControls button {
+  width: 40px;
+  height: 40px;
+  border: 1px solid var(--orionplace-text);
+  background: var(--orionplace-surface);
+  color: var(--orionplace-text);
+  /* The same text-sm as the banner and events arrows. */
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 20px;
+  cursor: pointer;
+}
+.scrollControls button:focus-visible {
+  background: var(--orionplace-hover);
+}
+@media (hover: hover) {
+  .scrollControls button:hover {
+    background: var(--orionplace-hover);
+  }
+}
+.scrollControls button:disabled { opacity: .4; cursor: default; }
+@container products (min-width: 660px) {
+  .track { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+}
+@container products (min-width: 900px) {
+  .track { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+}
+@container products (min-width: 1200px) {
+  .track { grid-template-columns: repeat(5, minmax(0, 1fr)); }
+}
+/* A narrow group (below 592px of its own width, the old 640px screen). */
+@container products (width < 592px) {
+  .track:not(.grid) {
+    grid-template-columns: none;
+    grid-auto-flow: column;
+    grid-template-rows: repeat(8, auto);
+    grid-auto-columns: min(62%, 256px);
+    overflow-x: auto;
+    scroll-snap-type: x mandatory;
+    overscroll-behavior-x: contain;
+  }
+  .track.grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .track > * { min-width: 0; scroll-snap-align: start; }
+  /* The row scrolls sideways, so card pictures leave sideways swipes to it. */
+  .track:not(.grid) [data-product-photo-swipe] { touch-action: auto; }
+}