orionplace-react 0.1.0 → 0.2.0

package/templates/components/orionplace/storefront/StorefrontHome.tsx

@@ -0,0 +1,282 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+import type {
+  MouseEvent,
+  ReactNode,
+} from 'react';
+import {
+  useOrionplace,
+  useOrionplaceCatalog,
+  useOrionplaceProducts,
+  useOrionplaceSelections,
+} from '@/providers/OrionplaceProvider';
+import { selectInit } from '@/stores/orionplace';
+import type {
+  IAppLoadCommonBanner,
+  IAppLoadCommonEvents,
+  ICategory,
+} from '@/interfaces/orionplace';
+import { useOrionplaceMediaFormat } from '@/hooks/useOrionplaceMediaFormat';
+import {
+  homeBannerSlides,
+  homeCategories,
+  homeEvents,
+  homeProductSections,
+  type HomeProductSection,
+} from '@/lib/orionplace/homeContent';
+import { homeLabels } from '@/lib/orionplace/homeLabels';
+import { safePublicUrl } from '@/lib/orionplace/presentation';
+import { MainBanner } from '@/components/orionplace/banners/MainBanner';
+import { CategoryGroup } from '@/components/orionplace/categories/CategoryGroup';
+import { EventsBlock } from '@/components/orionplace/events/EventsBlock';
+import { ProductGroup } from '@/components/orionplace/products/ProductGroup';
+import type { ProductGroupProps } from '@/components/orionplace/products/ProductGroup';
+import styles from './StorefrontHome.module.css';
+
+type ProductEvents = Pick<
+  ProductGroupProps,
+  | 'onSelect'
+  | 'onSelectSeller'
+  | 'onSelectVariant'
+  | 'onRequestSecondaryVariants'
+  | 'onSelectSecondaryVariant'
+  | 'onToggleFavorite'
+  | 'onAdd'
+  | 'onRemove'
+  | 'onSubscribe'
+  | 'onUnsubscribe'
+  | 'onPreorder'
+>;
+
+export interface StorefrontHomeProductRenderProps extends HomeProductSection {
+  disabled: boolean;
+  limit: number;
+}
+
+export interface StorefrontHomeProps extends ProductEvents {
+  productLimit?: number;
+  productActionsDisabled?: boolean;
+  categoryHref?: (categoryId: number) => string;
+  productHref?: ProductGroupProps['productHref'];
+  featuredHref?: (locale: string) => string;
+  onSelectCategory?: (category: ICategory) => void;
+  onSelectBanner?: (banner: IAppLoadCommonBanner) => void;
+  onSelectEvent?: (event: IAppLoadCommonEvents) => void;
+  onSelectFeatured?: () => void;
+  renderBanners?: () => ReactNode;
+  renderCategories?: () => ReactNode;
+  renderProducts?: (props: StorefrontHomeProductRenderProps) => ReactNode;
+  renderEvents?: () => ReactNode;
+}
+
+export function StorefrontHome({
+  productLimit = 12,
+  productActionsDisabled = false,
+  categoryHref,
+  productHref,
+  featuredHref = (locale) => `/featured?locale=${encodeURIComponent(locale)}`,
+  onSelectCategory,
+  onSelectBanner,
+  onSelectEvent,
+  onSelectFeatured,
+  renderBanners,
+  renderCategories,
+  renderProducts,
+  renderEvents,
+  onSelect,
+  onSelectSeller,
+  onSelectVariant,
+  onRequestSecondaryVariants,
+  onSelectSecondaryVariant,
+  onToggleFavorite,
+  onAdd,
+  onRemove,
+  onSubscribe,
+  onUnsubscribe,
+  onPreorder,
+}: StorefrontHomeProps) {
+  const init = useOrionplace(selectInit);
+  const catalog = useOrionplaceCatalog((state) => state.catalog);
+  const productInit = useOrionplaceProducts((state) => state.init);
+  const homeNewProductIds = useOrionplaceProducts(
+    (state) => state.homeNewProductIds,
+  );
+  const locale = useOrionplaceSelections((state) => state.localeCode);
+  const format = useOrionplaceMediaFormat();
+  const labels = homeLabels(locale);
+  const categories = useMemo(
+    () => homeCategories(catalog, init?.visual_settings),
+    [catalog, init?.visual_settings],
+  );
+  const banners = useMemo(
+    () => homeBannerSlides(init, locale, format),
+    [init, locale, format],
+  );
+  const events = useMemo(
+    () => homeEvents(init, locale),
+    [init, locale],
+  );
+  const productSections = useMemo(
+    () => homeProductSections(
+      productInit?.products ?? [],
+      productInit?.featured ?? [],
+      homeNewProductIds,
+    ),
+    [productInit, homeNewProductIds],
+  );
+  const sections = useMemo(() => [
+    ...productSections.filter((section) => section.key !== 'featured'),
+    {
+      key: 'events' as const,
+      collection: 'products' as const,
+      productIds: [],
+    },
+    ...productSections.filter((section) => section.key === 'featured'),
+  ], [productSections]);
+  const [expanded, setExpanded] = useState<ReadonlySet<string>>(new Set());
+
+  useEffect(() => {
+    setExpanded(new Set());
+  }, [init, productLimit]);
+
+  function sectionLimit(section: string) {
+    return expanded.has(section) ? 0 : productLimit;
+  }
+
+  function expand(section: string) {
+    setExpanded((current) => new Set(current).add(section));
+  }
+
+  function openFeatured(event: MouseEvent<HTMLAnchorElement>) {
+    const modified = event.button > 0 || event.metaKey || event.ctrlKey ||
+      event.shiftKey || event.altKey;
+    if (modified) {
+      return;
+    }
+
+    event.preventDefault();
+    onSelectFeatured?.();
+  }
+
+  const featured = safePublicUrl(featuredHref(locale)) || '/featured';
+
+  // The page follows its own width: a size container around the grid, so
+  // the docs tabs and every placement show the same spacing and headings.
+  return (
+    <div
+      className={styles.root}
+      data-storefront-home
+    >
+      <div
+        className={`${styles.home} ${banners.length ? '' : styles.withoutBanner}`.trim()}
+      >
+        {banners.length > 0 && (
+          <div data-home-part="MainBanner">
+            {renderBanners?.() ?? (
+              <MainBanner
+                categoryHref={categoryHref}
+                onSelect={onSelectBanner}
+              />
+            )}
+          </div>
+        )}
+        {categories.length > 0 && (
+          <section
+            className={styles.section}
+            data-home-part="CategoryGroup"
+            aria-label={labels.categories}
+          >
+            <h2 className={styles.heading}>{labels.categories}</h2>
+            {renderCategories?.() ?? (
+              <CategoryGroup
+                categoryHref={categoryHref}
+                onSelect={onSelectCategory}
+              />
+            )}
+          </section>
+        )}
+        {sections.map((section) => {
+          if (section.key === 'events') {
+            return events.length > 0 ? (
+              <section
+                key="events"
+                className={styles.section}
+                data-home-part="EventsBlock"
+                aria-label={labels.events}
+              >
+                <h2 className={styles.heading}>{labels.events}</h2>
+                {renderEvents?.() ?? (
+                  <EventsBlock onSelect={onSelectEvent} />
+                )}
+              </section>
+            ) : null;
+          }
+
+          const limit = sectionLimit(section.key);
+          const renderProps = {
+            ...section,
+            disabled: productActionsDisabled,
+            limit,
+          };
+
+          return (
+            <section
+              key={section.key}
+              id={section.key}
+              className={styles.section}
+              data-home-part="ProductGroup"
+              data-home-collection={section.collection}
+              data-home-section={section.key}
+              aria-label={labels[section.key]}
+            >
+              <header className={styles.sectionHeader}>
+                <h2 className={styles.heading}>{labels[section.key]}</h2>
+                {section.key === 'featured' ? (
+                  <a
+                    href={featured}
+                    className={styles.more}
+                    data-home-featured-link
+                    onClick={openFeatured}
+                  >
+                    {labels.viewAll}
+                    <span aria-hidden="true">↗</span>
+                  </a>
+                ) : limit > 0 && section.productIds.length > limit ? (
+                  <button
+                    type="button"
+                    className={styles.more}
+                    onClick={() => expand(section.key)}
+                  >
+                    {labels.viewAll}
+                    <span aria-hidden="true">↗</span>
+                  </button>
+                ) : null}
+              </header>
+              {renderProducts?.(renderProps) ?? (
+                <ProductGroup
+                  productIds={section.productIds}
+                  collection={section.collection}
+                  limit={limit}
+                  disabled={productActionsDisabled}
+                  productHref={productHref}
+                  onSelect={onSelect}
+                  onSelectSeller={onSelectSeller}
+                  onSelectVariant={onSelectVariant}
+                  onRequestSecondaryVariants={onRequestSecondaryVariants}
+                  onSelectSecondaryVariant={onSelectSecondaryVariant}
+                  onToggleFavorite={onToggleFavorite}
+                  onAdd={onAdd}
+                  onRemove={onRemove}
+                  onSubscribe={onSubscribe}
+                  onUnsubscribe={onUnsubscribe}
+                  onPreorder={onPreorder}
+                />
+              )}
+            </section>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/templates/components/orionplace/storefront/StorefrontWishlistButton.README.md

@@ -0,0 +1,51 @@
+# StorefrontWishlistButton
+
+## English
+
+`StorefrontWishlistButton` shows the current number of saved products. The
+initial count comes from `init.variables.c_wishlist` in Application Load.
+Wishlist actions can replace that value through `setProductCounters`; the
+replacement remains active across an Application Load refresh and is cleared
+when the product store resets. A dash is shown while no count is available.
+
+The component renders a real link to the selected locale's wishlist. `href`
+replaces that destination. A plain click prevents navigation and calls
+`onSelect`, so the application can open its wishlist route. A modifier click
+keeps the browser's normal link behavior. `disabled` removes the destination
+and prevents selection. `label` replaces the localized caption; `compact`
+visually hides the caption while retaining it in the accessible name.
+
+### Props
+
+| Prop                    | Meaning                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------ |
+| `label?: string`        | Caption of the link; empty uses the localized “Wishlist” caption.                             |
+| `compact?: boolean`     | Hides the caption visually and keeps it in the accessible name; the count stays visible. |
+| `disabled?: boolean`    | Removes the link destination and ignores clicks; the count stays visible.                 |
+| `href?: string`         | Link destination; empty uses `/wishlist?locale=<current language>`.                        |
+| `onSelect?: () => void` | Pressing the wishlist button calls the handler without arguments. The application opens the wishlist. |
+
+## Русский
+
+`StorefrontWishlistButton` показывает текущее количество сохранённых товаров.
+Начальное значение приходит из `init.variables.c_wishlist` в ответе Загрузки приложения.
+Действия с избранным могут заменить его через `setProductCounters`; это значение
+сохраняется при обновлении Загрузки приложения и очищается при сбросе хранилища
+товаров. Пока значение неизвестно, компонент показывает тире.
+
+Компонент выводит настоящую ссылку на избранное для выбранного языка. `href`
+заменяет адрес. Обычное нажатие отменяет переход и вызывает `onSelect`, чтобы
+приложение открыло свой маршрут избранного. Нажатие с модификатором сохраняет
+обычное поведение ссылки. `disabled` удаляет адрес и блокирует выбор. `label`
+заменяет локализованную подпись; `compact` визуально скрывает её, но сохраняет в
+доступном имени.
+
+### Свойства
+
+| Свойство                | Назначение                                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------------------------- |
+| `label?: string`        | Подпись ссылки; пустое значение использует локализованную подпись «Избранное».                   |
+| `compact?: boolean`     | Визуально скрывает подпись, сохраняя её в доступном имени; счётчик остаётся видимым.             |
+| `disabled?: boolean`    | Убирает адрес ссылки и игнорирует нажатия; счётчик остаётся видимым.                             |
+| `href?: string`         | Адрес ссылки; пустое значение использует `/wishlist?locale=<текущий язык>`.                      |
+| `onSelect?: () => void` | Нажатие кнопки избранного вызывает обработчик без аргументов. Приложение открывает список избранного. |

package/templates/components/orionplace/storefront/StorefrontWishlistButton.module.css

@@ -0,0 +1,95 @@
+.link {
+  position: relative;
+  display: inline-flex;
+  box-sizing: border-box;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  gap: 0.5rem;
+  min-width: 2.5rem;
+  height: 2.5rem;
+  padding: 0 0.5rem;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: 0.75rem;
+  line-height: 1rem;
+  letter-spacing: 0.08em;
+  text-decoration: none;
+  text-transform: uppercase;
+  cursor: pointer;
+  outline: none;
+}
+
+.withCaption {
+  padding-right: 1.5rem;
+}
+
+.link:focus-visible {
+  background: color-mix(in srgb, currentColor 10%, transparent);
+}
+
+@media (hover: hover) {
+  .link:not([aria-disabled='true']):hover {
+    background: color-mix(in srgb, currentColor 10%, transparent);
+  }
+}
+
+.link[aria-disabled='true'] {
+  cursor: default;
+  opacity: 0.5;
+}
+
+@media (hover: hover) {
+  .link[aria-disabled='true']:hover {
+    background: transparent;
+  }
+}
+
+.icon {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+.captionLine {
+  white-space: nowrap;
+}
+
+.count {
+  position: absolute;
+  top: 0.125rem;
+  right: 0.125rem;
+  box-sizing: border-box;
+  min-width: 1rem;
+  height: 1rem;
+  padding: 0 0.25rem;
+  border-radius: 9999px;
+  background: var(--orionplace-accent);
+  color: var(--orionplace-surface);
+  font-size: 0.625rem;
+  font-variant-numeric: tabular-nums;
+  line-height: 1rem;
+  letter-spacing: normal;
+  text-align: center;
+}
+
+/* Inside the dark header the count uses the header's inverse colors. */
+@container header (min-width: 0px) {
+  .count {
+    background: var(--orionplace-inverse-text);
+    color: var(--orionplace-inverse-surface);
+  }
+}
+
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/templates/components/orionplace/storefront/StorefrontWishlistButton.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+import type { MouseEvent } from 'react';
+import {
+  useOrionplaceProducts,
+  useOrionplaceSelections,
+} from '@/providers/OrionplaceProvider';
+import { headerLabels } from '@/lib/orionplace/headerLabels';
+import styles from './StorefrontWishlistButton.module.css';
+
+export interface StorefrontWishlistButtonProps {
+  label?: string;
+  compact?: boolean;
+  disabled?: boolean;
+  href?: string;
+  onSelect?: () => void;
+}
+
+export function StorefrontWishlistButton({
+  label    = '',
+  compact  = false,
+  disabled = false,
+  href     = '',
+  onSelect,
+}: StorefrontWishlistButtonProps) {
+  const locale  = useOrionplaceSelections((state) => state.localeCode);
+  const count   = useOrionplaceProducts((state) =>
+    state.productCounters.c_wishlist ??
+    state.init?.variables?.c_wishlist ??
+    '—'
+  );
+  const caption = label || headerLabels(locale).saved;
+  const target  = href || `/wishlist?locale=${encodeURIComponent(locale)}`;
+
+  function select(event: MouseEvent<HTMLAnchorElement>) {
+    if (disabled) {
+      event.preventDefault();
+      return;
+    }
+
+    const modified = event.button > 0 || event.metaKey || event.ctrlKey ||
+      event.shiftKey || event.altKey;
+    if (modified) {
+      return;
+    }
+
+    event.preventDefault();
+    onSelect?.();
+  }
+
+  return (
+    <a
+      href={disabled ? undefined : target}
+      aria-disabled={disabled || undefined}
+      aria-label={`${caption} · ${count}`}
+      className={`${styles.link} ${compact ? '' : styles.withCaption}`.trim()}
+      data-header-wishlist
+      onClick={select}
+    >
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        aria-hidden="true"
+        className={styles.icon}
+      >
+        <path
+          d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1.1-1.1a5.5 5.5 0 0 0-7.8 7.8L12 21l8.8-8.6a5.5 5.5 0 0 0 0-7.8Z"
+        />
+      </svg>
+      <span className={styles.captionLine}>
+        <span className={compact ? styles.visuallyHidden : undefined}>
+          {caption} ·
+        </span>
+        <span className={styles.count}>{count}</span>
+      </span>
+    </a>
+  );
+}

package/templates/components/orionplace/stores/StorefrontStores.README.md

@@ -0,0 +1,87 @@
+# StorefrontStores · React
+
+## English
+
+`StorefrontStores` loads physical stores through `stores_get`, page by page,
+searches by name, city or address, and shows each returned store's name,
+address, access details, hours, phone and products link; cards already shown
+stay visible while another page loads.
+
+When Application Load provides `public_keys.map_key` and the current page
+contains a store with valid coordinates, the shared `DeliveryMap` appears with
+the list. Card and marker selection keep the map and list in sync; stores
+without coordinates stay in the list, and the list remains usable without a
+map key or when the map provider fails.
+
+The layout follows the width of the component itself, not the screen width, so
+it is the same wherever the component is placed: a wide component shows the map
+beside the list, a narrow one shows it above the list. Without a map, a wide
+component shows the store cards in two columns.
+
+`initialQuery` and `initialPage` open the list where the address left it;
+`onSearch(query)` and `onPageChange(page, query)` let the page write them back
+(`?q=`, `?page=`), so a reload or Back from a store's products opens the same
+list.
+
+`disabled` prevents requests and search or pagination actions. Source is
+maintained in `components/orionplace/stores/StorefrontStores.tsx`; the primary
+contract is `interfaces/orionplace/stores/IStoreDirectory.ts`.
+
+### Props
+
+| Prop                                                                    | Meaning                                                                                      |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `storeId?: number`                                                      | ID of the store handled by StorefrontStores.                                                 |
+| `initialQuery?: string`                                                 | The search the list opens with, for example from the address.                                |
+| `initialPage?: number`                                                  | The page the list loads first when no initial data is given.                                 |
+| `initial?: { data: IPhysicalStore[]; rpag: IApiPagination \| 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.                  |
+| `disabled?: boolean`                                                    | Disables the component controls and prevents new actions.                                    |
+| `productsHref?: (store: IPhysicalStore, locale: string) => string`      | Builds the products destination from the callback arguments.                                 |
+| `onLoad: (action: StoresLoadAction) => Promise<StorePage> \| StorePage` | Called when the component needs its primary data. The callback payload is shown in its type. |
+| `onSearch?: (query: string) => void`                                    | Called when the visitor submits search text. The callback payload is shown in its type.      |
+| `onPageChange?: (page: number, query: string) => void`                  | Called when the visitor requests another page. The callback payload is shown in its type.    |
+
+## Русский
+
+`StorefrontStores` загружает физические магазины через `stores_get` по
+страницам, ищет их по названию, городу или адресу и показывает название,
+адрес, сведения о доступе, часы работы, телефон и ссылку на товары; уже
+показанные карточки остаются на экране во время следующей загрузки.
+
+Когда Application Load содержит `public_keys.map_key` и на текущей странице
+есть магазин с координатами, вместе со списком появляется общая `DeliveryMap`.
+Выбор в карточке и на карте синхронизирует их, магазин без координат остаётся
+в списке, а список продолжает работать без ключа карты или при ошибке её
+загрузки.
+
+Раскладка зависит от ширины самого компонента, а не экрана, поэтому она
+одинакова, где бы компонент ни стоял: в широком компоненте карта стоит рядом
+со списком, в узком — над ним. Без карты широкий компонент показывает карточки
+магазинов в две колонки.
+
+`initialQuery` и `initialPage` открывают список там, где его оставил адрес;
+`onSearch(query)` и `onPageChange(page, query)` позволяют странице записать их
+обратно (`?q=`, `?page=`), поэтому после перезагрузки или возврата из товаров
+магазина открывается тот же список.
+
+`disabled` запрещает запросы, поиск и пагинацию. Исходный файл:
+`components/orionplace/stores/StorefrontStores.tsx`; основной контракт:
+`interfaces/orionplace/stores/IStoreDirectory.ts`.
+
+### Свойства
+
+| Свойство                                                                | Назначение                                                                                      |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `storeId?: number`                                                      | ID магазина, с которым работает StorefrontStores.                                               |
+| `initialQuery?: string`                                                 | Поиск, с которым открывается список, например из адреса.                                        |
+| `initialPage?: number`                                                  | Страница, которую список загружает первой без начальных данных.                                 |
+| `initial?: { data: IPhysicalStore[]; rpag: IApiPagination \| null; }`   | Начальные данные с сервера для первого рендера и гидратации.                                    |
+| `initialError?: string`                                                 | Начальное значение ошибки, полученное на сервере для первого рендера и гидратации.              |
+| `loadOnMount?: boolean`                                                 | Запускает загрузку после гидратации, если серверные данные не переданы.                         |
+| `disabled?: boolean`                                                    | Блокирует элементы компонента и новые действия.                                                 |
+| `productsHref?: (store: IPhysicalStore, locale: string) => string`      | Строит адрес ссылки товаров из аргументов обработчика.                                          |
+| `onLoad: (action: StoresLoadAction) => Promise<StorePage> \| StorePage` | Вызывается, когда компоненту нужны основные данные. Данные обработчика указаны в его типе.      |
+| `onSearch?: (query: string) => void`                                    | Вызывается, когда покупатель отправляет поисковый текст. Данные обработчика указаны в его типе. |
+| `onPageChange?: (page: number, query: string) => void`                  | Вызывается, когда покупатель открывает другую страницу. Данные обработчика указаны в его типе.  |