orionplace-react 0.1.0 → 0.2.0

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

@@ -0,0 +1,152 @@
+# ProductCard
+
+## English
+
+Combines a product's main image, seller, name, variants, price, badges,
+wishlist state and available purchase actions. `productId` identifies the
+current product in `collection` (`products` by default or `featured`).
+`initialProduct` supplies that complete product during server rendering when
+it came from a parent request rather than Application Load.
+`compact` places the image beside the main information once the card itself
+is at least 22rem (352px) wide, and above it in a narrower card (the card's
+own width decides, not the screen); `details` keeps the
+purchase information for a product page and overrides `compact`. There the
+variant rows are the customer's choice, so Add puts the shown variant into the
+cart without asking again.
+`purchaseActions={false}` hides the cart, notification, preorder and wishlist
+controls. `variantProductIds` limits which product variants may be chosen.
+
+The first photo is present in guest server HTML with browser lazy loading and
+reserved dimensions. A regular card shows `images.small` (or `images.full` when
+there are no small photos); a compact card prefers `images.full`. With several
+photos, moving the mouse across the picture shows the photo of the strip under
+the pointer, a sideways swipe on a touch screen steps through them, and bars at
+the bottom show the open photo; leaving the picture restores the first. The
+other photos load once the customer points at or touches the picture. A
+`ProductGroup` row that scrolls sideways on a phone keeps the swipe for
+scrolling (`touch-action: auto` on `[data-product-photo-swipe]`); your own
+sideways-scrolling rows can do the same. Clicking any photo or the product name calls `onSelect`
+with the displayed product. `productHref`, when provided, makes the image
+and name links in server HTML and lets modified clicks use normal browser
+navigation. Badges, wishlist and purchase controls follow the visible edges
+of the photo. Variant choices stay on a scrollable row in regular cards.
+
+Selecting a variant swaps the card to its loaded product. If the storefront
+must fetch that product, it marks the target as loading in the product store;
+the card shows a loading state and blocks purchase actions until the target
+is supplied. A failed request keeps the current product and shows an error.
+Selecting a secondary variant applies its supplied product and preserves the
+loaded secondary choices before `onSelectSecondaryVariant` is called. The
+application can observe that event while the card owns the displayed selection.
+Purchase, wishlist and seller callbacks pass the IDs or
+objects needed by the storefront; API requests and subsequent store updates
+remain with the application. `renderAfterPrice` and `renderFooter` receive the
+displayed product and provide the equivalent of the Nuxt named slots.
+
+### Props
+
+| Prop                                                                                                              | Meaning                                                                                                              |
+| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `productId: number`                                                                                               | ID of the product handled by ProductCard.                                                                            |
+| `initialProduct?: IProduct`                                                                                       | Server-provided initial product used for the first render and hydration.                                             |
+| `collection?: OrionplaceProductCollection`                                                                        | Product-store collection used to resolve the supplied product ID.                                                    |
+| `compact?: boolean`                                                                                               | Larger representative layout: the image beside the details once the card itself is at least 22rem (352px) wide, above them in a narrower card; leaves out the description, badges, rating and stock notice. |
+| `details?: boolean`                                                                                               | Purchase-panel mode for a product page: no image, name, seller, rating or description; the chosen main variant above the choices, actions with text labels and `renderAfterPrice` after the price. Overrides `compact`. |
+| `disabled?: boolean`                                                                                              | Disables the component controls and prevents new actions.                                                            |
+| `actionsDisabled?: boolean`                                                                                       | Disables product actions while the surrounding flow is busy.                                                         |
+| `purchaseActions?: boolean`                                                                                       | Shows or hides the product purchase controls.                                                                        |
+| `variantProductIds?: number[]`                                                                                    | Product IDs available as variants of the current product.                                                            |
+| `productHref?: (id: number) => string`                                                                            | Builds the product destination from the callback arguments.                                                          |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+| `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. |
+| `renderAfterPrice?: (product: IProduct) => ReactNode`                                                             | Replaces the default after price region; the renderer inputs are shown in its type.                                  |
+| `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.                                                                         |
+| `dataCatalogProduct?: number`                                                                                     | Adds the catalog-product data marker used by the storefront layout.                                                  |
+
+## Русский
+
+Объединяет основную фотографию, продавца, название, варианты, цену, отметки,
+избранное и доступные действия с товаром. `productId` задаёт текущий товар
+в `collection` (`products` по умолчанию или `featured`). `initialProduct`
+передаёт полный объект этого товара для серверного HTML,
+если его вернул родительский запрос, а не Application Load. `compact`
+располагает фотографию рядом с основной информацией, когда сама карточка
+шире 22rem (352px), а в более узкой карточке — над ней (решает ширина
+карточки, а не экрана). `details` оставляет
+информацию о покупке для страницы товара и имеет приоритет над `compact`.
+Там вариант выбирают в строках вариантов, поэтому «Добавить» кладёт в корзину
+показанный вариант без повторного вопроса.
+`purchaseActions={false}` скрывает корзину, уведомление, предзаказ и
+избранное. `variantProductIds` ограничивает доступные варианты товара.
+
+Первая фотография есть в серверном HTML гостя, занимает заранее отведённое
+место и загружается браузером по мере необходимости. Обычная карточка
+показывает `images.small` (а если их нет — `images.full`), компактная
+предпочитает `images.full`. Если фотографий несколько, движение мыши по
+изображению показывает фотографию полосы под указателем, движение пальца
+влево или вправо листает их на сенсорном экране, а полоски внизу показывают
+открытую фотографию; уход указателя возвращает первую. Остальные фотографии
+загружаются, когда покупатель наводит указатель на изображение или касается
+его. Ряд `ProductGroup`, который на телефоне прокручивается вбок, оставляет
+движение пальца для прокрутки (`touch-action: auto` для
+`[data-product-photo-swipe]`); так же можно поступить в своих горизонтальных
+рядах. Нажатие на любую фотографию
+или название вызывает `onSelect` с показанным товаром. Если передан
+`productHref`, фотография и название становятся ссылками в серверном HTML.
+Щелчок с модификатором сохраняет обычное поведение браузера. Метки, избранное
+и действия покупки остаются у видимых краёв фотографии. В обычной карточке
+варианты остаются в одном ряду с горизонтальной прокруткой.
+
+При выборе варианта карточка показывает соответствующий загруженный товар.
+Если магазин должен его загрузить, он отмечает целевой товар как загружаемый
+в хранилище: карточка показывает ожидание и блокирует действия покупки до
+получения товара. При ошибке текущий товар остаётся на месте и появляется
+сообщение. При выборе дополнительного варианта карточка сохраняет переданный
+товар и загруженные дополнительные варианты до вызова
+`onSelectSecondaryVariant`. Приложение может обработать это событие; выбор
+показанного товара уже применён карточкой.
+
+Обработчики покупки, избранного и продавца
+передают магазину нужные ID и объекты; магазин выполняет запросы
+к API и обновляет хранилище. `renderAfterPrice` и `renderFooter` получают
+показанный товар и заменяют одноимённые слоты Nuxt.
+
+### Свойства
+
+| Свойство                                                                                                          | Назначение                                                                                                         |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `productId: number`                                                                                               | ID товара, с которым работает ProductCard.                                                                         |
+| `initialProduct?: IProduct`                                                                                       | Начальное значение товара, полученное на сервере для первого рендера и гидратации.                                 |
+| `collection?: OrionplaceProductCollection`                                                                        | Коллекция store товаров, в которой компонент ищет переданный ID товара.                                            |
+| `compact?: boolean`                                                                                               | Увеличенная карточка представителя: фотография рядом с данными, когда сама карточка шире 22rem (352px), и над ними в более узкой; без описания, отметок, оценки и сообщения о наличии. |
+| `details?: boolean`                                                                                               | Режим блока покупки для страницы товара: без фотографии, названия, продавца, оценки и описания; выбранный основной вариант над вариантами, действия с подписями и `renderAfterPrice` после цены. Имеет приоритет над `compact`. |
+| `disabled?: boolean`                                                                                              | Блокирует элементы компонента и новые действия.                                                                    |
+| `actionsDisabled?: boolean`                                                                                       | Блокирует действия с товаром, пока внешний сценарий занят.                                                         |
+| `purchaseActions?: boolean`                                                                                       | Показывает или скрывает действия покупки товара.                                                                   |
+| `variantProductIds?: number[]`                                                                                    | ID товаров, доступных как варианты текущего товара.                                                                |
+| `productHref?: (id: number) => string`                                                                            | Строит адрес ссылки товара из аргументов обработчика.                                                              |
+| `onSelect?: (product: IProduct) => void`                                                                          | Передаёт объект отображаемого товара при выборе его изображения или названия. Приложение выполняет переход к товару. |
+| `onSelectSeller?: (seller: IProductSeller) => void`                                                               | Передаёт объект продавца отображаемого товара при выборе продавца. Приложение открывает его страницу. |
+| `onToggleFavorite?: (selection: ProductActionSelection & { selected: boolean; }) => void`                         | Передаёт ID товара в `product` и желаемое состояние избранного в `selected` после нажатия сердца. Приложение подтверждает изменение запросом и обновляет данные товара. |
+| `onSelectVariant?: (selection: ProductActionSelection & { variant: IProductVariantValue; }) => void`              | Передаёт ID ранее отображаемого товара в `product` и выбранный основной вариант в `variant`. Доступный товар выбранного варианта заменяет карточку; отсутствующие данные загружает приложение. |
+| `onSelectSecondaryVariant?: (selection: ProductActionSelection & { variant: IProductSecondaryVariant; }) => void` | Передаёт ID ранее отображаемого товара в `product` и выбранный дополнительный вариант в `variant` после замены отображаемого товара. Выбор сохраняет данные дополнительных вариантов. |
+| `onRequestSecondaryVariants?: (request: IProductSecondaryVariantRequest) => void`                                 | Передаёт ID товара в `product`, ID группы товаров в `productGroup` и основной вариант в `variant`, когда для него нужно загрузить дополнительные варианты. Приложение загружает и передаёт их в хранилище товаров. |
+| `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` при выборе предзаказа. Приложение собирает необходимые контактные данные и отправляет запрос. |
+| `renderAfterPrice?: (product: IProduct) => ReactNode`                                                             | Заменяет стандартный блок содержимого после цены; входные данные функции указаны в её типе.                        |
+| `renderFooter?: (product: IProduct) => ReactNode`                                                                 | Заменяет стандартный блок нижней части; входные данные функции указаны в её типе.                                  |
+| `className?: string`                                                                                              | Дополнительный CSS-класс корневого элемента.                                                                       |
+| `dataCatalogProduct?: number`                                                                                     | Добавляет служебную отметку товара каталога для разметки магазина.                                                 |

package/templates/components/orionplace/products/ProductCard.module.css

@@ -0,0 +1,333 @@
+.card {
+  box-sizing: border-box;
+  display: grid;
+  min-width: 0;
+  align-content: start;
+  gap: 0;
+  color: var(--orionplace-text);
+  font-family: inherit;
+}
+.card:not(.compact):not(.details) {
+  width: 100%;
+  max-width: 288px;
+}
+/*
+ * A compact card puts the photo beside the text from 22rem of its own
+ * width (a measuring box for its parts, which take both columns below
+ * that).
+ */
+.compact {
+  container-type: inline-size;
+  grid-template-columns: minmax(0, 11rem) minmax(0, 1fr);
+  gap: 12px 20px;
+}
+.compact > * {
+  grid-column: 1 / -1;
+}
+.details {
+  gap: 20px;
+}
+/* The product page shows the price larger, as in the other packages. */
+.details > [data-product-part='ProductCardPrice'] span {
+  font-size: 1.5rem;
+  line-height: 2rem;
+}
+.imageArea {
+  position: relative;
+  width: 100%;
+  min-width: 0;
+  align-self: start;
+}
+.mediaOverlay {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  aspect-ratio: 3 / 4;
+  pointer-events: none;
+}
+.overlaidBadges {
+  position: absolute;
+  top: calc(var(--product-photo-inset-y, 0px) + 8px);
+  left: calc(var(--product-photo-inset-x, 0px) + 8px);
+  max-width: calc(100% - 56px - 2 * var(--product-photo-inset-x, 0px));
+  pointer-events: none;
+}
+.overlaidFavorite {
+  position: absolute;
+  top: calc(var(--product-photo-inset-y, 0px) + 4px);
+  right: calc(var(--product-photo-inset-x, 0px) + 4px);
+  pointer-events: auto;
+}
+.overlaidActions {
+  position: absolute;
+  right: calc(var(--product-photo-inset-x, 0px) + 8px);
+  bottom: calc(var(--product-photo-inset-y, 0px) + 8px);
+  max-width: calc(100% - 16px - 2 * var(--product-photo-inset-x, 0px));
+  pointer-events: auto;
+}
+.loadingOverlay {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  background: color-mix(
+    in srgb,
+    var(--orionplace-surface) 50%,
+    transparent
+  );
+  pointer-events: none;
+}
+.spinner {
+  width: 24px;
+  height: 24px;
+  border: 2px solid var(--orionplace-text);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: spin 700ms linear infinite;
+}
+.heading {
+  display: grid;
+  min-width: 0;
+  align-content: start;
+  gap: 4px;
+}
+.heading:empty {
+  display: none;
+}
+.productLink {
+  display: block;
+  width: 100%;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: var(--orionplace-text);
+  text-align: left;
+  text-decoration: none;
+  font: inherit;
+  cursor: pointer;
+}
+@media (hover: hover) {
+  .productLink:hover {
+    opacity: 0.7;
+  }
+}
+.productLink:focus-visible {
+  background: var(--orionplace-hover);
+}
+.productLink:disabled {
+  cursor: default;
+  opacity: 0.5;
+}
+.error {
+  margin: 0;
+  color: var(--orionplace-danger);
+  font-size: 12px;
+  line-height: 20px;
+}
+.screenReaderOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+.variantCaption {
+  margin: 0 0 -8px;
+  color: var(--orionplace-muted);
+  font-size: 12px;
+  line-height: calc(16 / 12);
+}
+.variantCaption span {
+  color: var(--orionplace-text);
+}
+.detailActions {
+  display: flex;
+  align-items: start;
+  gap: 8px;
+  padding-top: 8px;
+}
+.detailActions > :first-child {
+  flex: 1;
+  min-width: 0;
+}
+.detailActions [data-product-favorite] {
+  width: 44px;
+  height: 44px;
+  border-radius: 0;
+  border-color: var(--orionplace-text);
+}
+.card:not(.compact):not(.details) > [data-product-image] {
+  grid-row: 1;
+}
+.card:not(.compact):not(.details) > [data-product-heading] {
+  grid-row: 2;
+  margin-top: 12px;
+}
+.card:not(.compact):not(.details) > [data-product-part='ProductCardVariants'] {
+  grid-row: 3;
+  margin-top: 10px;
+}
+.card:not(.compact):not(.details) > [data-product-part='ProductCardPrice'] {
+  grid-row: 4;
+  margin-top: 8px;
+}
+.card:not(.compact):not(.details) > [data-product-part='ProductCardRating'] {
+  grid-row: 5;
+  margin-top: 8px;
+}
+.card:not(.compact):not(.details)
+  > [data-product-part='ProductCardStockNotice'] {
+  grid-row: 6;
+  margin-top: 4px;
+}
+.card:not(.compact):not(.details)
+  > [data-product-part='ProductCardDescription'] {
+  grid-row: 7;
+  margin-top: 8px;
+}
+.card:not(.compact):not(.details) > [data-product-footer] {
+  grid-row: 8;
+  margin-top: 12px;
+}
+.card:not(.compact):not(.details) [data-product-variants] [role='group'] > div {
+  flex-wrap: nowrap;
+  overflow-x: auto;
+  /* Room for the swatches' 24px touch targets, without moving the row. */
+  margin: -2px -3px;
+  padding: 3px;
+  scrollbar-width: thin;
+}
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+@container (width >= 22rem) {
+  .compact > * {
+    grid-column: 2;
+  }
+  .compact > .imageArea {
+    grid-column: 1;
+    grid-row: span 3;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation: none;
+  }
+}
+
+.imageLink {
+  position: relative;
+  display: block;
+  width: 100%;
+  aspect-ratio: 3 / 4;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  background: transparent;
+  cursor: pointer;
+  outline: none;
+  transition: opacity 150ms;
+}
+
+/* The title button keeps the card's font (`font: inherit` above); the
+   browser's button font made the title Arial when the card had no link. */
+button.imageLink {
+  font: revert;
+}
+@media (hover: hover) {
+  .imageLink:hover {
+    opacity: 0.85;
+  }
+}
+
+.imageLink:focus-visible {
+  opacity: 0.7;
+}
+
+.image {
+  box-sizing: border-box;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  transition: opacity 200ms;
+}
+
+/* Further photos lie over the first one; only the shown photo is visible. */
+.stackedImage {
+  position: absolute;
+  inset: 0;
+}
+
+.compact .image.stackedImage {
+  height: 100%;
+}
+
+.hiddenImage {
+  opacity: 0;
+}
+
+/* Sideways moves on a picture with several photos switch the photo. */
+.imageLink[data-product-photo-swipe] {
+  touch-action: pan-y;
+}
+
+/* One segment per photo zone along the picture's bottom edge, below the buttons. */
+.photoBars {
+  position: absolute;
+  right: calc(var(--product-photo-inset-x, 0px) + 8px);
+  bottom: calc(var(--product-photo-inset-y, 0px) + 2px);
+  left: calc(var(--product-photo-inset-x, 0px) + 8px);
+  display: flex;
+  gap: 4px;
+  pointer-events: none;
+}
+
+.photoBar {
+  display: block;
+  flex: 1;
+  height: 2px;
+  background: color-mix(in srgb, var(--orionplace-text) 20%, transparent);
+  transition: background-color 150ms;
+}
+
+.activePhotoBar {
+  background: var(--orionplace-accent);
+}
+
+.compact .imageArea {
+  max-width: 208px;
+}
+
+.compact .mediaOverlay {
+  height: 100%;
+  aspect-ratio: auto;
+}
+
+.compact .imageLink {
+  aspect-ratio: auto;
+}
+
+.compact .image {
+  height: 208px;
+}
+
+@container (width >= 22rem) {
+  .compact .imageArea {
+    max-width: 176px;
+  }
+  .compact .image {
+    height: 176px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .imageLink,
+  .image,
+  .photoBar {
+    transition: none;
+  }
+}