orionplace-react 0.1.0 → 0.2.1

package/templates/components/orionplace/address/StorefrontAddresses.README.md

@@ -0,0 +1,99 @@
+# StorefrontAddresses
+
+## English
+
+`StorefrontAddresses` shows the signed-in customer's saved delivery addresses.
+On mount and retry, `onLoad` receives `{ filters: {} }` for `address_get`. Set
+`loadOnMount` to `false` when `addresses` already contain server data. Each
+card shows its label, localized country flag when available, region, city,
+street, house and apartment. Empty address parts are skipped, and the current
+default delivery address is marked.
+
+Add and Edit mount `AddressForm`; editing is unavailable while another form is
+open. After the form reports confirmed addresses, `onSaved` receives that list
+and the component asks the host to reload; the form stays open and shows the
+saved address until Done closes it.
+The default action calls `onSetDefault` with the address and the inverse of its
+current `is_default_for_shipping` value. An address in a country without delivery (`country.is_shipping_country` is false) is marked «No delivery to this country» and its default action is disabled: the backend accepts it as a saved address, but never as the default or the cart's address. Delete first opens confirmation beside
+that address and calls `onDelete` only after confirmation. A successful default
+change or deletion requests the address list again. A failed default change or
+deletion shows the backend's message, or the general failure text, in the red
+notice; failed deletion keeps the confirmation visible so the customer can
+retry.
+
+Each card's menu supports pointer and keyboard use. ArrowDown opens and focuses
+the first available action; ArrowUp focuses the last. Arrow keys, Home and End
+move through enabled actions. Escape closes the menu and returns focus to its
+button. Tab and a pointer press outside close it.
+
+`useAccountAddresses()` (`hooks/useAccountAddresses.ts`) returns every prop
+with its requests, the address form included, as the starter's addresses
+page uses it: `<StorefrontAddresses {...useAccountAddresses()} />`. Pass
+`{ initial, initialError }` with a list the server already read, and
+`{ api, locate }` to use another client or position source than the
+storefront's own client and the browser's geolocation.
+
+### Props
+
+| Prop                                                                                                    | Meaning                                                                                                |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `addresses?: readonly IUserAddress[]`                                                                   | Saved customer addresses shown by the component.                                                       |
+| `loaded?: boolean`                                                                                      | Distinguishes a confirmed empty result from data that has not loaded yet.                              |
+| `pending?: boolean`                                                                                     | Shows the loading state and blocks duplicate actions.                                                  |
+| `error?: string`                                                                                        | Customer-visible error for the component request; omit it when no request failed.                      |
+| `loadOnMount?: boolean`                                                                                 | Starts the load callback after hydration when server data was not supplied.                            |
+| `form?: Omit<AddressFormProps, "address" \| "onSaved" \| "onCancel" \| "onDone">`                                 | Address-form state and callbacks shared with the address list.                                         |
+| `onLoad?: (request: IUserAddressListRequest) => Promise<void> \| void`                                  | Called when the component needs its primary data. The callback payload is shown in its type.           |
+| `onSetDefault?: (request: IUserAddressShippingRequest, address: IUserAddress) => Promise<void> \| void` | Called when the visitor makes an address the default. The callback payload is shown in its type.       |
+| `onDelete?: (address: IUserAddress) => Promise<void> \| void`                                           | Called when the visitor requests deletion. The callback payload is shown in its type.                  |
+| `onSaved?: (addresses: IUserAddress[]) => void`                                                         | Called when the current record has been saved successfully. The callback payload is shown in its type. |
+
+## Русский
+
+`StorefrontAddresses` показывает сохранённые адреса доставки вошедшего
+покупателя. После монтирования и при повторе `onLoad` получает `{ filters: {} }`
+для `address_get`. Укажите `loadOnMount={false}`, если `addresses` уже содержат
+серверные данные. В карточке выводятся название, локализованный флаг страны при
+его наличии, регион, город, улица, дом и квартира. Пустые части адреса
+пропускаются, а текущий основной адрес доставки отмечается отдельно.
+
+Добавление и изменение монтируют `AddressForm`; изменение недоступно, пока уже
+открыта другая форма. После подтверждённого сохранения `onSaved` получает
+список адресов, и компонент просит родителя обновить данные; форма остаётся
+открытой и показывает сохранённый адрес, пока «Готово» её не закроет.
+Действие основного адреса вызывает `onSetDefault` с адресом и значением,
+обратным текущему `is_default_for_shipping`. Удаление сначала показывает
+подтверждение рядом с выбранным адресом и вызывает `onDelete` только после него.
+После успешной смены основного адреса или удаления список запрашивается снова.
+Ошибка смены основного адреса или удаления выводится в красном уведомлении
+(сообщение бэкенда или общий текст ошибки); при ошибке удаления подтверждение
+остаётся открытым, чтобы действие можно было повторить.
+
+Меню каждой карточки работает с указателем и клавиатурой. ArrowDown открывает
+его и переводит фокус на первое доступное действие, ArrowUp — на последнее.
+Стрелки, Home и End перемещают фокус между доступными действиями. Escape
+закрывает меню и возвращает фокус на его кнопку. Tab и нажатие вне меню также
+закрывают его.
+
+`useAccountAddresses()` (`hooks/useAccountAddresses.ts`) возвращает все
+свойства вместе с запросами, включая форму адреса, — так их использует
+страница адресов стартового шаблона: `<StorefrontAddresses
+{...useAccountAddresses()} />`. Передайте `{ initial, initialError }`, если
+список уже прочитан на сервере, и `{ api, locate }`, чтобы использовать
+другой клиент или источник местоположения вместо клиента витрины и
+геолокации браузера.
+
+### Свойства
+
+| Свойство                                                                                                | Назначение                                                                                 |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `addresses?: readonly IUserAddress[]`                                                                   | Сохранённые адреса покупателя, которые показывает компонент.                               |
+| `loaded?: boolean`                                                                                      | Отличает подтверждённый пустой результат от ещё не загруженных данных.                     |
+| `pending?: boolean`                                                                                     | Показывает загрузку и блокирует повторные действия.                                        |
+| `error?: string`                                                                                        | Ошибка запроса для покупателя; не передавайте её, если запрос не завершился ошибкой.       |
+| `loadOnMount?: boolean`                                                                                 | Запускает загрузку после гидратации, если серверные данные не переданы.                    |
+| `form?: Omit<AddressFormProps, "address" \| "onSaved" \| "onCancel" \| "onDone">`                                 | Состояние и обработчики формы адреса, переданные списку адресов.                           |
+| `onLoad?: (request: IUserAddressListRequest) => Promise<void> \| void`                                  | Вызывается, когда компоненту нужны основные данные. Данные обработчика указаны в его типе. |
+| `onSetDefault?: (request: IUserAddressShippingRequest, address: IUserAddress) => Promise<void> \| void` | Вызывается, когда покупатель делает адрес основным. Данные обработчика указаны в его типе. |
+| `onDelete?: (address: IUserAddress) => Promise<void> \| void`                                           | Вызывается, когда покупатель запрашивает удаление. Данные обработчика указаны в его типе.  |
+| `onSaved?: (addresses: IUserAddress[]) => void`                                                         | Вызывается, когда текущая запись успешно сохранена. Данные обработчика указаны в его типе. |

package/templates/components/orionplace/address/StorefrontAddresses.module.css

@@ -0,0 +1,271 @@
+.section {
+  display: grid;
+  gap: 1.25rem;
+  min-width: 0;
+  color: var(--orionplace-text);
+  container-type: inline-size;
+}
+
+.heading,
+.error,
+.confirmationActions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: .75rem;
+}
+
+.heading {
+  justify-content: space-between;
+}
+
+.heading > div {
+  display: grid;
+  gap: 1.25rem;
+}
+
+.heading h1,
+.heading p,
+.record p,
+.confirmation p {
+  margin: 0;
+}
+
+.heading h1 {
+  font-size: 1.5rem;
+  font-weight: 500;
+  line-height: 1.25;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.heading p,
+.record p {
+  color: var(--orionplace-muted);
+}
+
+/* As `op-feature-button` and `op-feature-primary` in the other packages;
+   the country select keeps its own look. */
+.section :where(button:not([data-feature-part=OrionplaceSelect] *)) {
+  box-sizing: border-box;
+  display: inline-flex;
+  min-height: 2.75rem;
+  align-items: center;
+  justify-content: center;
+  gap: .5rem;
+  padding: .5rem 1.25rem;
+  border: 1px solid var(--orionplace-text);
+  background: transparent;
+  color: var(--orionplace-text);
+  font: inherit;
+  font-size: .75rem;
+  line-height: calc(1 / 0.75);
+  font-weight: 500;
+  letter-spacing: .08em;
+  text-transform: uppercase;
+  cursor: pointer;
+}
+
+.section :where(button:not([data-feature-part=OrionplaceSelect] *)):focus-visible {
+  background: var(--orionplace-hover);
+  outline: none;
+}
+
+@media (hover: hover) {
+  .section :where(button:not([data-feature-part=OrionplaceSelect] *)):hover:not(:disabled) {
+    background: var(--orionplace-hover);
+    outline: none;
+  }
+}
+
+.section :where(button:not([data-feature-part=OrionplaceSelect] *)):disabled {
+  cursor: default;
+  opacity: .6;
+}
+
+.section .primary {
+  border-color: var(--orionplace-accent);
+  background: var(--orionplace-accent);
+  color: var(--orionplace-surface);
+}
+
+.section .primary:focus-visible {
+  background: var(--orionplace-accent);
+  opacity: .85;
+}
+
+@media (hover: hover) {
+  .section .primary:hover:not(:disabled) {
+    background: var(--orionplace-accent);
+    opacity: .85;
+  }
+}
+
+.error {
+  padding: .75rem 1rem;
+  border: 1px solid var(--orionplace-danger);
+  color: var(--orionplace-danger);
+}
+
+.records {
+  display: grid;
+  gap: .75rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.record {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: start;
+  gap: 1rem;
+  padding: 1.25rem;
+  border: 1px solid var(--orionplace-border);
+}
+
+.recordContent,
+.confirmation {
+  display: grid;
+  gap: 1.25rem;
+  min-width: 0;
+}
+
+.title {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: .75rem;
+  overflow-wrap: anywhere;
+}
+
+.label {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.flag {
+  width: 1.5rem;
+  height: 1rem;
+  flex-shrink: 0;
+  background-size: cover;
+}
+
+/* A saved address in a country without delivery. */
+.noShipping {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+}
+
+/* Square badge: the default address, as in the other packages. */
+.default {
+  display: inline-block;
+  justify-self: start;
+  width: fit-content;
+  padding: 2px 8px;
+  background: var(--orionplace-inverse-surface);
+  color: var(--orionplace-inverse-text);
+  font-size: 11px;
+  line-height: 1.5;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.menuRoot {
+  position: relative;
+}
+
+.section .menuTrigger {
+  display: inline-flex;
+  width: 2.5rem;
+  height: 2.5rem;
+  min-height: 0;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border-color: transparent;
+}
+
+.menuTrigger svg {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+.menuTrigger:focus-visible,
+.menuTrigger[aria-expanded='true'] {
+  border-color: var(--orionplace-text);
+  background: var(--orionplace-hover);
+  outline: none;
+}
+
+@media (hover: hover) {
+  .menuTrigger:hover {
+    border-color: var(--orionplace-text);
+    background: var(--orionplace-hover);
+    outline: none;
+  }
+}
+
+.menu {
+  position: absolute;
+  z-index: 20;
+  top: calc(100% + .25rem);
+  right: 0;
+  box-sizing: border-box;
+  width: 16rem;
+  max-width: calc(100vw - 2rem);
+  border: 1px solid var(--orionplace-border);
+  background: var(--orionplace-surface);
+}
+
+.section .menu button {
+  display: flex;
+  width: 100%;
+  min-height: 0;
+  font-weight: 400;
+  justify-content: space-between;
+  padding: .75rem 1rem;
+  border: 0;
+  border-top: 1px solid var(--orionplace-border);
+  font-size: .75rem;
+  line-height: calc(1 / 0.75);
+  letter-spacing: .08em;
+  text-align: left;
+  text-transform: uppercase;
+}
+
+.section .menu button:first-child {
+  border-top: 0;
+}
+
+.section .menu button:focus-visible {
+  background: var(--orionplace-hover);
+  outline: none;
+}
+
+@media (hover: hover) {
+  .section .menu button:hover {
+    background: var(--orionplace-hover);
+    outline: none;
+  }
+}
+
+.section .menu button[data-danger='true'] {
+  color: var(--orionplace-danger);
+}
+
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* The title follows the component's own width, as in the other packages. */
+@container (min-width: 592px) {
+  .heading h1 { font-size: 1.875rem; }
+}