orionplace-react 0.1.0 → 0.2.1

package/templates/components/orionplace/subscriptions/StorefrontTariff.tsx

@@ -0,0 +1,474 @@
+'use client';
+
+import {
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import {
+  useOrionplace,
+  useOrionplaceCatalog,
+  useOrionplaceCatalogStore,
+  useOrionplaceSelections,
+} from '@/providers/OrionplaceProvider';
+import { selectIsAuthenticated } from '@/stores/orionplace';
+import type { IBreadcrumb } from '@/interfaces/orionplace/shared/IBreadcrumb';
+import type { ISubscribeTariff } from '@/interfaces/orionplace/subscribeTariff/ISubscribeTariff';
+import type { ITariffSelection } from '@/interfaces/orionplace/subscribeTariff/ITariffSelection';
+import type { ISubscriptionTariffsResponse } from '@/interfaces/orionplace/subscribes/ISubscriptionApi';
+import { safeBlogArticleHtml } from '@/lib/orionplace/blogArticleHtml';
+import { featureLabels } from '@/lib/orionplace/featureLabels';
+import { htmlTextParagraphs } from '@/lib/orionplace/htmlText';
+import {
+  getAvailableNestedValueFromObject,
+  plainText,
+  safePublicUrl,
+} from '@/lib/orionplace/presentation';
+import { subscriptionLabels } from '@/lib/orionplace/subscriptionLabels';
+import {
+  tariffMediaItems,
+  tariffPagePath,
+} from '@/lib/orionplace/tariffPage';
+import { tariffLabels } from '@/lib/orionplace/tariffLabels';
+import {
+  useOrionplaceTariffPurchase,
+  type TariffPurchaseActions,
+} from '@/hooks/useOrionplaceTariffPurchase';
+import { OrionplaceBreadcrumbs } from '@/components/orionplace/shared/OrionplaceBreadcrumbs';
+import { OrionplaceEmptyState } from '@/components/orionplace/shared/OrionplaceEmptyState';
+import { OrionplaceImage } from '@/components/orionplace/shared/OrionplaceImage';
+import { TariffCardFeatures } from '@/components/orionplace/tariffs/TariffCardFeatures';
+import { TariffCardPrices } from '@/components/orionplace/tariffs/TariffCardPrices';
+import { TariffSubscriptionModal } from '@/components/orionplace/tariffs/TariffSubscriptionModal';
+import styles from './StorefrontTariff.module.css';
+import { apiErrorMessage } from '@/lib/orionplace/api';
+
+type TariffsPage = NonNullable<ISubscriptionTariffsResponse['page_data']>;
+
+export interface TariffPageLoadAction {
+  endpoint: 'subscriptions_guest_search';
+  request: { filters: { id: number } };
+  signal: AbortSignal;
+}
+
+export interface StorefrontTariffProps extends TariffPurchaseActions {
+  tariffId: number;
+  preloaded?: boolean;
+  resume?: ITariffSelection;
+  initialError?: string;
+  loadOnMount?: boolean;
+  tariffsHref?: (locale: string) => string;
+  subscriptionsHref?: (locale: string) => string;
+  walletHref?: (locale: string) => string;
+  onLoad: (action: TariffPageLoadAction) => Promise<TariffsPage> | TariffsPage;
+  onRequireSignIn?: (returnPath: string) => void;
+  onLoaded?: (tariff: ISubscribeTariff) => void;
+  onMissing?: () => void;
+}
+
+export function StorefrontTariff({
+  tariffId,
+  preloaded = false,
+  resume,
+  initialError = '',
+  loadOnMount = true,
+  tariffsHref = (locale) => `/tariffs?locale=${encodeURIComponent(locale)}`,
+  subscriptionsHref,
+  walletHref,
+  onLoad,
+  onRequireSignIn,
+  onLoaded,
+  onMissing,
+  onSubscribe,
+  onLoadSubscriptions,
+  onLoadProfile,
+  onAccountLoaded,
+}: StorefrontTariffProps) {
+  const authenticated = useOrionplace(selectIsAuthenticated);
+  const catalogTariff = useOrionplaceCatalog((state) =>
+    state.tariffs?.data.find((entry) => entry.id === tariffId),
+  );
+  const catalogStore = useOrionplaceCatalogStore();
+  const locale = useOrionplaceSelections((state) => state.localeCode);
+  const copy = tariffLabels(locale);
+  const common = featureLabels(locale);
+  const pageCopy = subscriptionLabels(locale);
+  const callbacks = useRef({ onLoad, onLoaded, onMissing });
+  callbacks.current = { onLoad, onLoaded, onMissing };
+  const active = useRef<AbortController | undefined>(undefined);
+  const reported = useRef<number | undefined>(undefined);
+  const opened = useRef('');
+  const initiallyConfirmed = preloaded && Boolean(catalogTariff);
+  const automaticLoad = loadOnMount && !initiallyConfirmed && !initialError;
+  const [confirmedId, setConfirmedId] = useState<number | undefined>(
+    initiallyConfirmed ? tariffId : undefined,
+  );
+  const [settledId, setSettledId] = useState<number | undefined>(
+    initiallyConfirmed || initialError || !loadOnMount ? tariffId : undefined,
+  );
+  const [pending, setPending] = useState(automaticLoad);
+  const [error, setError] = useState(initialError);
+  const [mediaIndex, setMediaIndex] = useState(0);
+  const [period, setPeriod] = useState<number>();
+  const [option, setOption] = useState<number>();
+  const [selection, setSelection] = useState<ITariffSelection>();
+  const [hydrated, setHydrated] = useState(false);
+  const tariff = confirmedId === tariffId ? catalogTariff : undefined;
+  const purchase = useOrionplaceTariffPurchase(
+    {
+      onSubscribe,
+      onLoadSubscriptions,
+      onLoadProfile,
+      onAccountLoaded,
+    },
+    common.failed,
+  );
+  const busy = pending || purchase.pending;
+  // The heading names the plan; `tariff_title` is its SEO page title.
+  const title = getAvailableNestedValueFromObject(
+    tariff?.locales,
+    locale,
+    'tariff_name',
+  ) || getAvailableNestedValueFromObject(
+    tariff?.locales,
+    locale,
+    'tariff_title',
+  ) || String(tariffId);
+  const shortDescription = plainText(getAvailableNestedValueFromObject(
+    tariff?.locales,
+    locale,
+    'tariff_short_description',
+  ));
+  const descriptionSource = getAvailableNestedValueFromObject(
+    tariff?.locales,
+    locale,
+    'tariff_description',
+  ) || '';
+  const descriptionText = htmlTextParagraphs(descriptionSource);
+  const description = hydrated && descriptionSource
+    ? safeBlogArticleHtml(descriptionSource)
+    : '';
+  const media = tariffMediaItems(tariff);
+  const current = media[mediaIndex] ?? media[0];
+  const videoSource = current?.kind === 'video'
+    ? safePublicUrl(current.src)
+    : '';
+  const breadcrumbs: IBreadcrumb[] = [
+    {
+      id: 'tariffs',
+      label: copy.plans,
+      to: { path: '/tariffs', query: { locale } },
+    },
+    { id: `tariff-${tariffId}`, label: title },
+  ];
+  const showSkeleton = !tariff && !error && (
+    settledId !== tariffId || pending
+  );
+
+  async function load() {
+    if (active.current) {
+      return;
+    }
+    const controller = new AbortController();
+    const requestedId = tariffId;
+    active.current = controller;
+    setPending(true);
+    setError('');
+    try {
+      const page = await callbacks.current.onLoad({
+        endpoint: 'subscriptions_guest_search',
+        request: { filters: { id: requestedId } },
+        signal: controller.signal,
+      });
+      if (controller.signal.aborted || requestedId !== tariffId) {
+        return;
+      }
+      const found = page.data.find((entry) => entry.id === requestedId);
+      catalogStore.getState().setTariffs({
+        data: found ? [found] : [],
+        subscriptions: page.subscriptions,
+      });
+      setConfirmedId(found ? requestedId : undefined);
+      setSettledId(requestedId);
+      if (!found) {
+        callbacks.current.onMissing?.();
+      }
+    } catch (reason) {
+      if (!controller.signal.aborted) {
+        setError(
+          apiErrorMessage(reason) || common.failed,
+        );
+        setSettledId(requestedId);
+      }
+    } finally {
+      if (active.current === controller) {
+        active.current = undefined;
+        setPending(false);
+      }
+    }
+  }
+
+  function showMedia(index: number) {
+    if (media.length) {
+      setMediaIndex((index + media.length) % media.length);
+    }
+  }
+
+  function returnPath(value: ITariffSelection) {
+    if (!tariff) {
+      return tariffsHref(locale);
+    }
+    const query = new URLSearchParams({
+      locale,
+      tariff: String(value.tariff),
+      period: value.price === null ? 'trial' : String(value.price),
+    });
+    return `${tariffPagePath(tariff, locale)}?${query.toString()}`;
+  }
+
+  function choose(value: ITariffSelection) {
+    if (!authenticated) {
+      onRequireSignIn?.(returnPath(value));
+      return;
+    }
+    purchase.resetFeedback();
+    if (value.price !== null) {
+      setPeriod(value.price);
+    }
+    setSelection(value);
+  }
+
+  useEffect(() => setHydrated(true), []);
+
+  useEffect(() => {
+    active.current?.abort();
+    active.current = undefined;
+    reported.current = undefined;
+    opened.current = '';
+    setMediaIndex(0);
+    setPeriod(undefined);
+    setOption(undefined);
+    setSelection(undefined);
+    setError(initialError);
+    const hasPreloaded = preloaded && Boolean(catalogTariff);
+    setConfirmedId(hasPreloaded ? tariffId : undefined);
+    setSettledId(
+      hasPreloaded || initialError || !loadOnMount ? tariffId : undefined,
+    );
+    if (loadOnMount && !hasPreloaded && !initialError) {
+      void load();
+    } else {
+      setPending(false);
+    }
+    return () => {
+      active.current?.abort();
+      active.current = undefined;
+    };
+  }, [tariffId, preloaded]);
+
+  useEffect(() => {
+    if (tariff && reported.current !== tariff.id) {
+      reported.current = tariff.id;
+      callbacks.current.onLoaded?.(tariff);
+    }
+  }, [tariff]);
+
+  useEffect(() => {
+    if (
+      !resume ||
+      resume.tariff !== tariffId ||
+      !authenticated ||
+      !tariff
+    ) {
+      return;
+    }
+    const key = `${resume.tariff}:${resume.price ?? 'trial'}`;
+    if (opened.current === key) {
+      return;
+    }
+    opened.current = key;
+    choose(resume);
+  }, [resume?.tariff, resume?.price, authenticated, tariff]);
+
+  return (
+    <section
+      className={styles.root}
+      data-feature-part="StorefrontTariff"
+      aria-busy={busy || undefined}
+    >
+      {error ? (
+        <div className={`${styles.notice} ${styles.error}`} role="alert">
+          <p>{error}</p>
+          <button type="button" disabled={pending} onClick={() => void load()}>
+            {common.retry}
+          </button>
+        </div>
+      ) : null}
+      {busy || showSkeleton ? (
+        <p
+          className="op-feature-loading"
+          role="status"
+        >
+          <span className={styles.screenReaderOnly}>{common.loading}</span>
+        </p>
+      ) : null}
+      {tariff || showSkeleton ? (
+        <div className={styles.breadcrumbs}>
+          <OrionplaceBreadcrumbs items={breadcrumbs} loading={!tariff} />
+        </div>
+      ) : null}
+      {tariff ? (
+        <>
+          <div className={styles.layout}>
+            <section className={styles.gallery} aria-label={copy.gallery} data-tariff-gallery>
+              <div className={styles.stage}>
+                {current?.kind === 'image' ? (
+                  <OrionplaceImage
+                    src={current.src}
+                    alt={title}
+                    width={960}
+                    height={720}
+                    className={styles.mainMedia}
+                  />
+                ) : current?.kind === 'video' && videoSource ? (
+                  <video
+                    key={current.key}
+                    src={videoSource}
+                    poster={safePublicUrl(current.preview) || undefined}
+                    aria-label={copy.video}
+                    controls
+                    preload="metadata"
+                    className={styles.mainMedia}
+                  />
+                ) : (
+                  <p className={styles.unavailable}>{copy.unavailableMedia}</p>
+                )}
+                {media.length > 1 ? (
+                  <>
+                    <button
+                      type="button"
+                      className={`${styles.mediaButton} ${styles.previous}`}
+                      aria-label={copy.previousMedia}
+                      onClick={() => showMedia(mediaIndex - 1)}
+                    >
+                      <span aria-hidden="true">‹</span>
+                    </button>
+                    <button
+                      type="button"
+                      className={`${styles.mediaButton} ${styles.next}`}
+                      aria-label={copy.nextMedia}
+                      onClick={() => showMedia(mediaIndex + 1)}
+                    >
+                      <span aria-hidden="true">›</span>
+                    </button>
+                  </>
+                ) : null}
+              </div>
+              {media.length > 1 ? (
+                <div className={styles.thumbnails}>
+                  {media.map((item, index) => (
+                    <button
+                      key={item.key}
+                      type="button"
+                      aria-label={`${item.kind === 'video' ? copy.video : copy.image} ${index + 1}`}
+                      aria-pressed={index === mediaIndex}
+                      onClick={() => showMedia(index)}
+                    >
+                      {item.kind === 'image' ? (
+                        <OrionplaceImage
+                          src={item.src}
+                          alt=""
+                          width={96}
+                          height={96}
+                          className={styles.thumbnail}
+                        />
+                      ) : item.preview ? (
+                        <OrionplaceImage
+                          src={item.preview}
+                          alt=""
+                          width={96}
+                          height={96}
+                          className={styles.thumbnail}
+                        />
+                      ) : (
+                        <span aria-hidden="true">▶</span>
+                      )}
+                    </button>
+                  ))}
+                </div>
+              ) : null}
+            </section>
+            <div className={styles.details}>
+              <header>
+                <h1>{title}</h1>
+                {shortDescription ? <p>{shortDescription}</p> : null}
+              </header>
+              <div className={styles.purchase} data-tariff-purchase>
+                <TariffCardFeatures
+                  tariffId={tariff.id}
+                  period={period}
+                  option={option}
+                  onOptionChange={setOption}
+                />
+                <TariffCardPrices
+                  tariffId={tariff.id}
+                  selectedPeriod={period}
+                  disabled={busy || purchase.needsRefresh}
+                  onPeriodChange={setPeriod}
+                  onSelect={choose}
+                />
+              </div>
+              {purchase.needsRefresh && !purchase.pending ? (
+                <div className={styles.notice} role="status">
+                  <p>{pageCopy.refreshRequired}</p>
+                  <button type="button" onClick={() => void purchase.refresh()}>
+                    {common.refresh}
+                  </button>
+                </div>
+              ) : null}
+            </div>
+          </div>
+          {descriptionSource ? (
+            <section className={styles.description} data-tariff-description>
+              <h2>{copy.about}</h2>
+              {description ? (
+                <div dangerouslySetInnerHTML={{ __html: description }} />
+              ) : (
+                <div>
+                  {descriptionText.map((paragraph, index) => (
+                    <p key={`${index}-${paragraph}`}>{paragraph}</p>
+                  ))}
+                </div>
+              )}
+            </section>
+          ) : null}
+          {selection ? (
+            <TariffSubscriptionModal
+              tariffId={tariff.id}
+              price={selection.price}
+              option={option}
+              pending={purchase.pending}
+              suspended={purchase.needsRefresh}
+              error={purchase.error}
+              completed={purchase.completed}
+              subscriptionsHref={subscriptionsHref}
+              walletHref={walletHref}
+              onClose={() => setSelection(undefined)}
+              onSubmit={(request) => void purchase.subscribe(request)}
+            />
+          ) : null}
+        </>
+      ) : showSkeleton ? (
+        <div className={styles.skeleton} aria-hidden="true" data-tariff-skeleton>
+          <div />
+          <div><span /><span /><span /></div>
+        </div>
+      ) : !pending && !error ? (
+        <OrionplaceEmptyState
+          kind="subscriptions"
+          message={copy.notFound}
+        />
+      ) : null}
+    </section>
+  );
+}

package/templates/components/orionplace/subscriptions/StorefrontTariffs.README.md

@@ -0,0 +1,102 @@
+# StorefrontTariffs · React
+
+## English
+
+`StorefrontTariffs` reads the Application Load tariff collection from the
+isolated catalog store and groups plans by `tariff.subscription`, in response
+order. Each group uses the localized parent subscription name and plain-text
+description. A nonempty `ids` list keeps only those tariff IDs and adds an All
+link from `tariffsHref(locale)`. If the filtered list is empty, the empty state
+explains whether no plan matched the link, the submitted search, or the store's
+complete collection.
+
+Application Load data renders in the initial server HTML. When the collection
+is missing or an earlier search replaced it, hydration calls `onLoad` with
+`subscriptions_guest_search` and `filters.search_string: ''`. Submitting the
+trimmed search uses the same exact field. Reset submits an empty search. A
+successful response replaces the tariff catalog; a failed request preserves
+the current cards and shows Retry. Unmounting aborts an active list request.
+
+Guests receive the exact plan and period return address through
+`onRequireSignIn(returnPath)`. For a signed-in visitor, `resume` opens that
+choice when it is still available. Confirmation calls `onSubscribe` with
+`subscriptions_subscribe`, then refreshes account data through
+`onLoadSubscriptions` (`subscriptions_get`) and `onLoadProfile`
+(`profile_get`). `onAccountLoaded` receives both successful responses. If that
+required refresh fails, another purchase remains blocked and Refresh repeats
+both reads. Repeating the already confirmed request is ignored; a different
+plan can still be purchased.
+
+The component makes requests only through those callbacks. Source is
+maintained in
+`components/orionplace/subscriptions/StorefrontTariffs.tsx`; the response
+contract is `interfaces/orionplace/subscribes/ISubscriptionApi.ts`.
+
+### Props
+
+| Prop                                                                                                                 | Meaning                                                                                                       |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `resume?: ITariffSelection`                                                                                          | Restores the selected tariff and period after a sign-in return.                                               |
+| `ids?: number[]`                                                                                                     | Tariff IDs included in the rendered list.                                                                     |
+| `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.                                   |
+| `tariffsHref?: (locale: string) => string`                                                                           | Builds the tariffs destination from the callback arguments.                                                   |
+| `subscriptionsHref?: (locale: string) => string`                                                                     | Builds the subscriptions destination from the callback arguments.                                             |
+| `walletHref?: (locale: string) => string`                                                                            | Builds the wallet destination from the callback arguments.                                                    |
+| `onLoad: (action: TariffsLoadAction) => Promise<TariffsPage> \| TariffsPage`                                         | Called when the component needs its primary data. The callback payload is shown in its type.                  |
+| `onRequireSignIn?: (returnPath: string) => void`                                                                     | Called when the visitor must sign in before continuing. The callback payload is shown in its type.            |
+| `onListLoaded?: (page: TariffsPage) => void`                                                                         | Called when the tariff list has loaded successfully. The callback payload is shown in its type.               |
+| `onSubscribe: (action: TariffSubscribeAction) => Promise<void> \| void`                                              | Called when the visitor subscribes to the current product or plan. The callback payload is shown in its type. |
+| `onLoadSubscriptions: (action: TariffSubscriptionsRefreshAction) => Promise<SubscriptionsPage> \| SubscriptionsPage` | Called when the customer subscriptions must be refreshed. The callback payload is shown in its type.          |
+| `onLoadProfile: (action: TariffProfileRefreshAction) => Promise<ProfilePage> \| ProfilePage`                         | Called when the current profile must be refreshed. The callback payload is shown in its type.                 |
+| `onAccountLoaded?: (subscriptions: SubscriptionsPage, profile: ProfilePage) => void`                                 | Called when the refreshed account data is ready. The callback payload is shown in its type.                   |
+
+## Русский
+
+`StorefrontTariffs` читает коллекцию тарифов Application Load из отдельного
+хранилища каталога и группирует тарифы по `tariff.subscription` в порядке
+ответа. Заголовок группы содержит локализованное название родительской
+подписки и её обычное текстовое описание. Непустой список `ids` оставляет
+только указанные ID тарифов и добавляет ссылку «Все» из
+`tariffsHref(locale)`. Пустое состояние отдельно объясняет отсутствие тарифов
+из ссылки, результатов отправленного поиска или всей коллекции магазина.
+
+Данные Application Load входят в первоначальный серверный HTML. Если коллекции
+нет или её заменил предыдущий поиск, после гидратации `onLoad` получает
+`subscriptions_guest_search` и `filters.search_string: ''`. Отправка поиска
+использует то же поле с текстом без пробелов по краям. Сброс отправляет пустой
+поиск. Успешный ответ заменяет каталог тарифов; ошибка сохраняет текущие
+карточки и показывает повтор. При размонтировании активный запрос отменяется.
+
+Для гостя `onRequireSignIn(returnPath)` получает точный адрес выбранного тарифа
+и периода. Для авторизованного посетителя `resume` открывает этот выбор, если
+он ещё доступен. Подтверждение передаёт в `onSubscribe` действие
+`subscriptions_subscribe`, затем обновляет аккаунт через
+`onLoadSubscriptions` (`subscriptions_get`) и `onLoadProfile`
+(`profile_get`). `onAccountLoaded` получает оба успешных ответа. Если
+обязательное обновление не удалось, новое подключение блокируется, а кнопка
+обновления повторяет оба чтения. Повтор уже подтверждённого запроса
+игнорируется; другой тариф можно подключить.
+
+Компонент отправляет запросы только через эти функции. Исходный файл:
+`components/orionplace/subscriptions/StorefrontTariffs.tsx`; контракт ответа:
+`interfaces/orionplace/subscribes/ISubscriptionApi.ts`.
+
+### Свойства
+
+| Свойство                                                                                                             | Назначение                                                                                                         |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `resume?: ITariffSelection`                                                                                          | Восстанавливает выбранный тариф и период после возврата со входа.                                                  |
+| `ids?: number[]`                                                                                                     | ID тарифов, включённых в показанный список.                                                                        |
+| `initialError?: string`                                                                                              | Начальное значение ошибки, полученное на сервере для первого рендера и гидратации.                                 |
+| `loadOnMount?: boolean`                                                                                              | Запускает загрузку после гидратации, если серверные данные не переданы.                                            |
+| `tariffsHref?: (locale: string) => string`                                                                           | Строит адрес ссылки тарифов из аргументов обработчика.                                                             |
+| `subscriptionsHref?: (locale: string) => string`                                                                     | Строит адрес ссылки подписок из аргументов обработчика.                                                            |
+| `walletHref?: (locale: string) => string`                                                                            | Строит адрес ссылки кошелька из аргументов обработчика.                                                            |
+| `onLoad: (action: TariffsLoadAction) => Promise<TariffsPage> \| TariffsPage`                                         | Вызывается, когда компоненту нужны основные данные. Данные обработчика указаны в его типе.                         |
+| `onRequireSignIn?: (returnPath: string) => void`                                                                     | Вызывается, когда покупателю нужно войти перед продолжением. Данные обработчика указаны в его типе.                |
+| `onListLoaded?: (page: TariffsPage) => void`                                                                         | Вызывается, когда список тарифов успешно загружен. Данные обработчика указаны в его типе.                          |
+| `onSubscribe: (action: TariffSubscribeAction) => Promise<void> \| void`                                              | Вызывается, когда покупатель оформляет подписку на текущий товар или тариф. Данные обработчика указаны в его типе. |
+| `onLoadSubscriptions: (action: TariffSubscriptionsRefreshAction) => Promise<SubscriptionsPage> \| SubscriptionsPage` | Вызывается, когда нужно обновить подписки покупателя. Данные обработчика указаны в его типе.                       |
+| `onLoadProfile: (action: TariffProfileRefreshAction) => Promise<ProfilePage> \| ProfilePage`                         | Вызывается, когда нужно обновить текущий профиль. Данные обработчика указаны в его типе.                           |
+| `onAccountLoaded?: (subscriptions: SubscriptionsPage, profile: ProfilePage) => void`                                 | Вызывается, когда обновлённые данные аккаунта готовы. Данные обработчика указаны в его типе.                       |