orionplace-react 0.1.0 → 0.2.1

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

@@ -0,0 +1,183 @@
+# StorefrontSubscriptions · React
+
+## English
+
+`StorefrontSubscriptions` loads the signed-in customer with
+`onLoad({ endpoint: 'subscriptions_get', request: {} })`, then refreshes the
+profile and wallet with `onLoadProfile({ endpoint: 'profile_get', request:
+{ filters: {} } })`. `initialData` supplies server-rendered cards and prevents
+the initial subscriptions request. Each card resolves its plan from the owned
+subscription response and then from the plans the storefront sells
+(`storeTariffs` of the catalog store), so the plan of an expired subscription
+or a plan closed to new purchases remains visible. A plan search or a plan
+page does not change that list.
+
+Cards show the plan, active, ended or setup-pending state, creation and paid
+end dates, automatic-renewal duration and selected-currency amount, plan
+features, usage and filtered service details. A cancelled subscription keeps
+its paid end date and explains how selecting a renewal period starts renewal
+again.
+
+The action menu includes only valid actions. A paid plan can be extended and
+configured for renewal. An active subscription can move to another open plan
+in the same subscription group or another service option. Cancellation is
+available only while an active, renewable subscription has not already been
+cancelled. Support is always present and uses
+`ticketsHref(subscriptionId, locale)`.
+
+Each write callback receives the exact endpoint, request and `AbortSignal`.
+After a confirmed write, the component runs `subscriptions_get` and
+`profile_get` in order. A failed required refresh keeps further writes blocked
+and shows a retry action. `onAccountLoaded` receives both confirmed pages.
+Thrown errors may carry `fields` or `form_errors`; named messages appear beside
+the corresponding dialog controls.
+
+The menu supports arrow keys, Home, End, Escape, Tab and outside clicks. Dialog
+focus returns to the menu trigger. `renderPlanSummary` and
+`renderRemoteDetails` replace the two read-only card regions. Source is
+maintained in
+`components/orionplace/subscriptions/StorefrontSubscriptions.tsx`; request and
+response contracts are in
+`interfaces/orionplace/subscribes/ISubscriptionApi.ts`.
+
+### Props
+
+| Prop                                                                                                                  | Meaning                                                                                                    |
+| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `initialData?: { data: ICustomerSubscription[]; subscriptions: IPublicSubscription[]; tariffs: ISubscribeTariff[]; }` | 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.                                |
+| `plansHref?: (locale: string) => string`                                                                              | Builds the plans destination from the callback arguments.                                                  |
+| `walletHref?: (locale: string) => string`                                                                             | Builds the wallet destination from the callback arguments.                                                 |
+| `ticketsHref?: (subscriptionId: number, locale: string) => string`                                                    | Builds the tickets destination from the callback arguments.                                                |
+| `onLoad: (action: SubscriptionLoadAction) => Promise<SubscriptionsPage> \| SubscriptionsPage`                         | Called when the component needs its primary data. The callback payload is shown in its type.               |
+| `onLoadProfile: (action: SubscriptionProfileAction) => Promise<ProfilePage> \| ProfilePage`                           | Called when the current profile must be refreshed. The callback payload is shown in its type.              |
+| `onRenew: (action: SubscriptionMutationAction<ISubscriptionRenewRequest>) => Promise<void> \| void`                   | Called when the visitor renews or extends a subscription. The callback payload is shown in its type.       |
+| `onSetRenewal: (action: SubscriptionMutationAction<ISubscriptionRenewalSettingRequest>) => Promise<void> \| void`     | Called when the visitor changes automatic subscription renewal. The callback payload is shown in its type. |
+| `onChangeTariff: (action: SubscriptionMutationAction<ISubscriptionChangeTariffRequest>) => Promise<void> \| void`     | Called when the visitor changes the subscription tariff. The callback payload is shown in its type.        |
+| `onChangeOption: (action: SubscriptionMutationAction<ISubscriptionChangeOptionRequest>) => Promise<void> \| void`     | Called when the visitor changes a subscription option. The callback payload is shown in its type.          |
+| `onCancel: (action: SubscriptionMutationAction<ISubscriptionCancelRequest>) => Promise<void> \| void`                 | Passes the subscription cancellation action with `request.paid_subscription` after dialog confirmation. After the handler succeeds, the component refreshes subscriptions and profile data. |
+| `onRequireSignIn?: (returnPath: string) => void`                                                                      | Called when the visitor must sign in before continuing. The callback payload is shown in its type.         |
+| `onSupport?: (subscriptionId: number, href: string) => void`                                                          | Called when the visitor opens support for the current record. 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.                |
+| `renderPlanSummary?: (plan: ISubscribeTariff \| undefined, subscription: ICustomerSubscription) => ReactNode`         | Replaces the default plan summary region; the renderer inputs are shown in its type.                       |
+| `renderRemoteDetails?: (subscription: ICustomerSubscription) => ReactNode`                                            | Replaces the default remote details region; the renderer inputs are shown in its type.                     |
+
+## Русский
+
+`StorefrontSubscriptions` загружает данные вошедшего покупателя через
+`onLoad({ endpoint: 'subscriptions_get', request: {} })`, а затем обновляет
+профиль и кошелёк через `onLoadProfile({ endpoint: 'profile_get', request:
+{ filters: {} } })`. `initialData` задаёт карточки для серверного HTML и
+отменяет начальный запрос подписок. Тариф каждой карточки сначала ищется в
+ответе с подписками покупателя, затем в тарифах, которые продаёт магазин
+(`storeTariffs` хранилища каталога), поэтому тариф истёкшей подписки или тариф,
+закрытый для новых покупок, остаётся видимым. Поиск тарифов и страница тарифа
+этот список не меняют.
+
+Карточки показывают тариф, действующее, завершённое или подключаемое состояние,
+даты подключения и конца оплаченного периода, длительность и сумму
+автопродления в выбранной валюте, возможности тарифа, использование и
+отфильтрованные данные сервиса. У отменённой подписки сохраняется дата конца
+оплаченного периода и поясняется, как выбор периода снова включает
+автопродление.
+
+Меню содержит только доступные действия. Платный тариф можно продлить и
+настроить для автопродления. Действующую подписку можно перевести на другой
+открытый тариф той же подписки или на другую опцию сервиса. Отмена доступна
+только для действующей подписки с автопродлением, которая ещё не отменена.
+Поддержка доступна всегда и использует
+`ticketsHref(subscriptionId, locale)`.
+
+Каждый обработчик записи получает точное имя эндпоинта, запрос и
+`AbortSignal`. После подтверждённой записи компонент последовательно вызывает
+`subscriptions_get` и `profile_get`. Если обязательное обновление не удалось,
+новые изменения блокируются и появляется повторная загрузка.
+`onAccountLoaded` получает оба подтверждённых ответа. Выброшенная ошибка может
+содержать `fields` или `form_errors`; именованные сообщения выводятся рядом с
+соответствующими полями диалога.
+
+Меню поддерживает стрелки, Home, End, Escape, Tab и щелчок снаружи. После
+диалога фокус возвращается кнопке меню. `renderPlanSummary` и
+`renderRemoteDetails` заменяют две информационные области карточки. Исходный
+файл: `components/orionplace/subscriptions/StorefrontSubscriptions.tsx`;
+контракты запросов и ответов:
+`interfaces/orionplace/subscribes/ISubscriptionApi.ts`.
+
+### Свойства
+
+| Свойство                                                                                                              | Назначение                                                                                                    |
+| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `initialData?: { data: ICustomerSubscription[]; subscriptions: IPublicSubscription[]; tariffs: ISubscribeTariff[]; }` | Начальные данные с сервера для первого рендера и гидратации.                                                  |
+| `initialError?: string`                                                                                               | Начальное значение ошибки, полученное на сервере для первого рендера и гидратации.                            |
+| `loadOnMount?: boolean`                                                                                               | Запускает загрузку после гидратации, если серверные данные не переданы.                                       |
+| `plansHref?: (locale: string) => string`                                                                              | Строит адрес ссылки тарифов из аргументов обработчика.                                                        |
+| `walletHref?: (locale: string) => string`                                                                             | Строит адрес ссылки кошелька из аргументов обработчика.                                                       |
+| `ticketsHref?: (subscriptionId: number, locale: string) => string`                                                    | Строит адрес ссылки обращений из аргументов обработчика.                                                      |
+| `onLoad: (action: SubscriptionLoadAction) => Promise<SubscriptionsPage> \| SubscriptionsPage`                         | Вызывается, когда компоненту нужны основные данные. Данные обработчика указаны в его типе.                    |
+| `onLoadProfile: (action: SubscriptionProfileAction) => Promise<ProfilePage> \| ProfilePage`                           | Вызывается, когда нужно обновить текущий профиль. Данные обработчика указаны в его типе.                      |
+| `onRenew: (action: SubscriptionMutationAction<ISubscriptionRenewRequest>) => Promise<void> \| void`                   | Вызывается, когда покупатель продлевает подписку. Данные обработчика указаны в его типе.                      |
+| `onSetRenewal: (action: SubscriptionMutationAction<ISubscriptionRenewalSettingRequest>) => Promise<void> \| void`     | Вызывается, когда покупатель меняет автоматическое продление подписки. Данные обработчика указаны в его типе. |
+| `onChangeTariff: (action: SubscriptionMutationAction<ISubscriptionChangeTariffRequest>) => Promise<void> \| void`     | Вызывается, когда покупатель меняет тариф подписки. Данные обработчика указаны в его типе.                    |
+| `onChangeOption: (action: SubscriptionMutationAction<ISubscriptionChangeOptionRequest>) => Promise<void> \| void`     | Вызывается, когда покупатель изменяет опцию подписки. Данные обработчика указаны в его типе.                  |
+| `onCancel: (action: SubscriptionMutationAction<ISubscriptionCancelRequest>) => Promise<void> \| void`                 | Передаёт действие отмены подписки с `request.paid_subscription` после подтверждения диалога. После успешного обработчика компонент обновляет подписки и профиль. |
+| `onRequireSignIn?: (returnPath: string) => void`                                                                      | Вызывается, когда покупателю нужно войти перед продолжением. Данные обработчика указаны в его типе.           |
+| `onSupport?: (subscriptionId: number, href: string) => void`                                                          | Вызывается, когда покупатель открывает поддержку для текущей записи. Данные обработчика указаны в его типе.   |
+| `onAccountLoaded?: (subscriptions: SubscriptionsPage, profile: ProfilePage) => void`                                  | Вызывается, когда обновлённые данные аккаунта готовы. Данные обработчика указаны в его типе.                  |
+| `renderPlanSummary?: (plan: ISubscribeTariff \| undefined, subscription: ICustomerSubscription) => ReactNode`         | Заменяет стандартный блок сводки тарифа; входные данные функции указаны в её типе.                            |
+| `renderRemoteDetails?: (subscription: ICustomerSubscription) => ReactNode`                                            | Заменяет стандартный блок удалённых данных; входные данные функции указаны в её типе.                         |
+## Response fields and application actions
+
+The following tables describe the response and the supplied composition’s follow-up actions. The framework-specific props and events above identify which work belongs to the component and which belongs to its parent.
+
+### English
+
+### How response fields become a subscription card
+
+`subscriptions_get.page_data` — data contains purchased subscriptions; tariffs contains the plan of each subscription’s current (last) period, including expired subscriptions and plans closed to new purchases.
+
+| Field or condition | Meaning and application action |
+| --- | --- |
+| `data[].tariff` → `tariffs[].id` | The supplied list combines these plans with the public catalog, preferring the account response for matching IDs. `option` selects the matching plan option. A missing plan leaves plan-dependent actions unavailable. |
+| `plugin.remote_subscription_sync_pending: true` | Show Pending while service confirmation is awaited. This check takes precedence over the end date. |
+| Otherwise, `active_until.days_ago < 0` | Show Active. The response’s end date is still in the future. |
+| Otherwise, missing or elapsed `active_until` | Show Ended. A saved `renew_period` alone does not establish active access. |
+| `cancelled_date` and `renew_period` | A cancellation date marks renewal as stopped. Customer cancellation keeps the paid access end date. `renew_period: null` means automatic renewal is off; see `subscriptions_get` for the complete cancellation-date lifecycle. |
+
+### When menu actions are offered
+
+| Field or condition | Meaning and application action |
+| --- | --- |
+| Extend | The resolved plan has paid-period choices in `prices`. |
+| Automatic renewal | The plan has period choices, or the subscription already has `renew_period` so it can be disabled even without a loaded plan. |
+| Change plan | Status is Active or Pending, the current plan is known, and another available plan of the same subscription definition has a positive-duration paid period. |
+| Change option | Never offered: the storefront backend refuses `subscriptions_change_option`, because another service option is another server. The customer cancels the subscription and subscribes with the new option. |
+| Cancel renewal | Status is Active, `cancelled_date` is absent, and the plan has period choices or renewal is already configured. |
+| After a confirmed change | Reload `subscriptions_get` and `profile_get`: use the returned plan, dates, renewal, pending flag and wallet balance. If this reload fails, refresh before another chargeable change. |
+
+### Русский
+
+### Как поля ответа становятся карточкой подписки
+
+`subscriptions_get.page_data` — data содержит купленные подписки; tariffs — тариф текущего (последнего) периода каждой подписки, включая истёкшие подписки и тарифы, закрытые для новых покупок.
+
+| Поле или условие | Значение и действие приложения |
+| --- | --- |
+| `data[].tariff` → `tariffs[].id` | Готовый список объединяет эти тарифы с общедоступным каталогом; при одинаковом ID приоритет у ответа аккаунта. `option` выбирает опцию тарифа. Без найденного тарифа зависимые от него действия недоступны. |
+| `plugin.remote_subscription_sync_pending: true` | Выводится ожидание подтверждения сервиса. Эта проверка имеет приоритет над датой окончания. |
+| Иначе, `active_until.days_ago < 0` | Подписка активна: дата окончания из ответа ещё не наступила. |
+| Иначе, `active_until` отсутствует или истёк | Подписка завершена. Одно сохранённое `renew_period` не подтверждает активный доступ. |
+| `cancelled_date` и `renew_period` | Дата отмены помечает остановку продления. Отмена покупателем сохраняет дату окончания оплаченного доступа. `renew_period: null` означает отключённое автопродление; полный жизненный цикл даты отмены описан в `subscriptions_get`. |
+
+### Когда доступны пункты меню
+
+| Поле или условие | Значение и действие приложения |
+| --- | --- |
+| Продление | У найденного тарифа есть варианты оплачиваемого периода в `prices`. |
+| Автопродление | У тарифа есть периоды либо у подписки уже задано `renew_period`: его можно отключить и без загруженного тарифа. |
+| Смена тарифа | Подписка активна или ожидает подтверждения, текущий тариф известен, а другой доступный тариф той же подписки имеет платный период положительной длительности. |
+| Смена опции | Не предлагается: бэкенд витрины отклоняет `subscriptions_change_option`, потому что другая опция сервиса — это другой сервер. Покупатель отменяет подписку и оформляет новую с нужной опцией. |
+| Отмена продления | Подписка активна, `cancelled_date` отсутствует, у тарифа есть периоды или уже настроено продление. |
+| После подтверждённого изменения | Загрузите `subscriptions_get` и `profile_get`: используйте полученные тариф, даты, продление, признак ожидания и баланс. Если обновление не удалось, повторите его до следующего действия с оплатой. |
+
+[English guide](https://orionmarket.place/en/sandbox/components/react/subscriptions) · [Русский](https://orionmarket.place/ru/sandbox/components/react/subscriptions)

package/templates/components/orionplace/subscriptions/StorefrontSubscriptions.module.css

@@ -0,0 +1,347 @@
+.root {
+  display: flex;
+  width: 100%;
+  flex-direction: column;
+  gap: 1.5rem;
+  color: var(--orionplace-text);
+  font-family: inherit;
+  container-type: inline-size;
+}
+
+.pageHeader {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: end;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.pageHeader h1 {
+  margin: 0;
+  font-size: 1.5rem;
+  line-height: 1.25;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+/* The page's own link, as `commerce-link` in the other packages; the links
+   inside the dialogs keep their own look. */
+.pageHeader a {
+  display: inline-flex;
+  width: fit-content;
+  align-items: center;
+  align-self: flex-start;
+  gap: 0.25rem;
+  padding-bottom: 0.125rem;
+  border-bottom: 1px solid currentColor;
+  color: var(--orionplace-text);
+  font-size: 0.75rem;
+  line-height: 1rem;
+  letter-spacing: 0.08em;
+  outline: none;
+  text-decoration: none;
+  text-transform: uppercase;
+}
+
+.pageHeader a:focus-visible {
+  opacity: 0.7;
+}
+
+@media (hover: hover) {
+  .pageHeader a:hover {
+    opacity: 0.7;
+  }
+}
+
+.pageHeader svg {
+  width: 1rem;
+  height: 1rem;
+}
+
+.notice {
+  display: grid;
+  justify-items: start;
+  gap: 0.75rem;
+  padding: 1rem;
+  border: 1px solid var(--orionplace-border);
+}
+
+.notice p,
+.attention {
+  margin: 0;
+  font-size: 0.875rem;
+  line-height: 1.5rem;
+}
+
+.error {
+  border-color: var(--orionplace-danger);
+  color: var(--orionplace-danger);
+}
+
+.notice button {
+  min-height: 2.5rem;
+  padding: 0 1rem;
+  border: 1px solid currentColor;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.75rem;
+  line-height: calc(1 / 0.75);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.loading {
+  min-height: 15rem;
+}
+
+.card {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  border: 1px solid var(--orionplace-border);
+  background: var(--orionplace-surface);
+}
+
+.cardHeader {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 1rem;
+}
+
+.identity {
+  display: grid;
+  min-width: 0;
+  gap: 0.5rem;
+}
+
+.identity h2 {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin: 0;
+  font-size: 0.875rem;
+  line-height: calc(1.25 / 0.875);
+  font-weight: 500;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.identity h2 svg,
+.facts svg,
+.menuTrigger svg {
+  width: 1.25rem;
+  height: 1.25rem;
+  flex: none;
+}
+
+.states {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.state {
+  display: inline-flex;
+  align-items: center;
+  gap: .5rem;
+  padding: 0.25rem 0.75rem;
+  border: 1px solid var(--orionplace-border);
+  background: var(--orionplace-muted-surface);
+  color: var(--orionplace-muted);
+  font-size: 0.75rem;
+  line-height: calc(1 / 0.75);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.state svg {
+  width: .875rem;
+  height: .875rem;
+  flex-shrink: 0;
+  stroke-width: 2;
+}
+
+.state[data-state='active'] {
+  border-color: var(--orionplace-success);
+  color: var(--orionplace-success);
+}
+
+.state[data-state='ended'] {
+  border-color: var(--orionplace-danger);
+  color: var(--orionplace-danger);
+}
+
+.state[data-state='pending'],
+.state[data-state='cancelled'] {
+  border-color: var(--orionplace-attention);
+  color: var(--orionplace-attention);
+}
+
+.menuRoot {
+  position: relative;
+  flex: none;
+}
+
+.menuTrigger {
+  display: grid;
+  width: 2.5rem;
+  height: 2.5rem;
+  place-items: center;
+  padding: 0;
+  border: 1px solid transparent;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+
+.menuTrigger:focus-visible,
+.menuTrigger[aria-expanded='true'] {
+  border-color: var(--orionplace-border);
+  background: var(--orionplace-hover);
+}
+
+@media (hover: hover) {
+  .menuTrigger:hover {
+    border-color: var(--orionplace-border);
+    background: var(--orionplace-hover);
+  }
+}
+
+.menu {
+  position: absolute;
+  z-index: 20;
+  top: 100%;
+  right: 0;
+  box-sizing: border-box;
+  width: 18rem;
+  max-width: calc(100vw - 2rem);
+  margin-top: 0.25rem;
+  border: 1px solid var(--orionplace-border);
+  background: var(--orionplace-surface);
+}
+
+.menu button {
+  display: flex;
+  width: 100%;
+  min-height: 2.75rem;
+  align-items: center;
+  padding: 0.75rem 1rem;
+  border: 0;
+  border-top: 1px solid var(--orionplace-border);
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.75rem;
+  line-height: calc(1 / 0.75);
+  letter-spacing: 0.08em;
+  text-align: left;
+  text-transform: uppercase;
+}
+
+.menu button svg {
+  width: 1rem;
+  height: 1rem;
+  flex: none;
+  margin-right: 0.75rem;
+}
+
+.menu button:first-child {
+  border-top: 0;
+}
+
+.menu button:focus-visible {
+  background: var(--orionplace-hover);
+}
+
+@media (hover: hover) {
+  .menu button:hover {
+    background: var(--orionplace-hover);
+  }
+}
+
+.menu button[data-danger='true'] {
+  color: var(--orionplace-danger);
+}
+
+.menu button:disabled,
+.notice button:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.part {
+  padding: 1.25rem 1rem;
+  border-top: 1px solid var(--orionplace-border);
+}
+
+.attention {
+  padding: 0.875rem 1rem;
+  border: 1px solid var(--orionplace-attention);
+  color: var(--orionplace-attention);
+}
+
+.facts {
+  display: grid;
+  gap: 1rem 2rem;
+  margin: 0;
+  background: var(--orionplace-muted-surface);
+}
+
+.facts div {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  align-items: center;
+  gap: 0.25rem 0.75rem;
+}
+
+.facts svg {
+  grid-row: span 2;
+  color: var(--orionplace-muted);
+}
+
+.facts dt {
+  color: var(--orionplace-muted);
+  font-size: 0.75rem;
+  line-height: calc(1 / 0.75);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.facts dd {
+  margin: 0;
+  font-size: 0.875rem;
+  line-height: calc(1.25 / 0.875);
+}
+
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+/* The page's own width, not the screen's, as in the other packages. */
+@container (min-width: 592px) {
+  .cardHeader,
+  .part {
+    padding-right: 1.5rem;
+    padding-left: 1.5rem;
+  }
+
+  .facts {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+}
+
+/* The title follows the component's own width, as in the other packages. */
+@container (min-width: 592px) {
+  .pageHeader h1 { font-size: 1.875rem; }
+}