orionplace-react 0.1.0 → 0.2.0

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

@@ -0,0 +1,152 @@
+# AddressForm
+
+## English
+
+`AddressForm` creates or edits one delivery address. Existing address values
+initialize the fields. A new form starts empty. Country and region are required
+before saving; the label, city, street and house use native required-field
+validation. Additional address line, entrance, intercom, floor, apartment and
+postal code remain optional. Inputs stop at the backend's length limits: label
+32 characters, city, street and additional line 128, postal code 64, house,
+entrance, intercom, floor and apartment 20.
+
+On mount, `onLoadCountries` receives the `reload_customer_app` request for
+`fUserAddress.country`. When an existing address is edited, its regions are
+requested after country loading finishes. Changing the country clears region,
+city, street, house and postal code and reports a region search. Changing the
+region clears the same address fields below it. Region searches use
+`onSearchRegions`; duplicate region IDs are removed from the displayed choices
+while the selected region keeps its caption.
+
+City and street input waits briefly after the latest change before reporting
+`onSuggestCity` or `onSuggestStreet`. Suggestions require a country that
+supports them and a selected region; street suggestions also require a city.
+Selecting a city clears the street and applies its postal code. Selecting a
+street preserves the current postal code when the suggestion has none.
+
+When Application Load enables coordinate lookup, the location button calls
+`onLocate`. The host obtains permission, calls the coordinate endpoint and
+returns the matched country and region with the suggested address. Successful
+`onSave` returns the confirmed address list and then triggers `onSaved`.
+
+After a successful save the form shows the address as the backend saved it
+(the first returned address): label, country, region, city, street, house,
+postal code and the non-empty details. A country's address plugin can
+normalize the city, street, house, second line and postal code; fields that
+differ from what was sent are marked “refined” and an attention notice asks the
+customer to check them, otherwise a success notice confirms the address. Focus
+moves to the “Address saved” heading. **Edit** returns to the form with the
+saved values, and the next save edits that address (`address_edit`, also after
+a new address was added). **Done** calls `onDone`; the host closes the form.
+Editing never clears the default delivery mark: for the default address the
+checkbox stays checked and disabled with a hint to use the address menu. When the chosen country has no delivery, the default checkbox is cleared and disabled with a note: the backend refuses such an address as the default.
+
+`useOrionplaceAddressForm()` shows the localized failure texts of the other
+frameworks: a region search, suggestion or location failure shows its own
+message, and a failed save or country load shows the backend's field messages
+or the general failure text.
+
+### Props
+
+| Prop                                                                                                | Meaning                                                                                                |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `address?: IUserAddress`                                                                            | Saved address being edited; omit it when creating a new address.                                       |
+| `countries?: readonly IAddressCountryOption[]`                                                      | Countries available for the address form.                                                              |
+| `regions?: readonly IAddressRegion[]`                                                               | Regions available for the selected address country.                                                    |
+| `cities?: readonly IAddressCitySuggestion[]`                                                        | City suggestions for the current address text.                                                         |
+| `streets?: readonly IAddressSuggestion[]`                                                           | Street suggestions for the current city and entered text.                                              |
+| `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.                      |
+| `fieldErrors?: Readonly<Record<string, string>>`                                                    | Validation messages keyed by the submitted field name.                                                 |
+| `optionsPending?: boolean`                                                                          | Shows that the options request is running and blocks duplicate actions.                                |
+| `optionsError?: string`                                                                             | Customer-visible error from the options request.                                                       |
+| `regionPending?: boolean`                                                                           | Shows that the region request is running and blocks duplicate actions.                                 |
+| `regionError?: string`                                                                              | Customer-visible error from the region request.                                                        |
+| `hintPending?: "" \| "city" \| "street"`                                                            | Shows that the hint request is running and blocks duplicate actions.                                   |
+| `hintError?: string`                                                                                | Customer-visible error from the hint request.                                                          |
+| `geoPending?: boolean`                                                                              | Shows that the geo request is running and blocks duplicate actions.                                    |
+| `geoError?: string`                                                                                 | Customer-visible error from the geo request.                                                           |
+| `onLoadCountries?: (action: AddressCountriesAction) => Promise<void> \| void`                       | Called when the address form needs its countries. The callback payload is shown in its type.           |
+| `onSearchRegions?: (request: IAddressRegionSearchRequest) => void`                                  | Called when the address form searches regions. The callback payload is shown in its type.              |
+| `onSuggestCity?: (request: { country: number; region: number; search_string: string; }) => void`    | Called when the address form requests city suggestions. The callback payload is shown in its type.     |
+| `onSuggestStreet?: (request: IAddressSuggestionRequest) => void`                                    | Called when the address form requests street suggestions. The callback payload is shown in its type.   |
+| `onLocate?: () => Promise<AddressLocationResult \| null> \| AddressLocationResult \| null`          | Called when the visitor requests coordinates for the address. The callback has no payload.             |
+| `onSave?: (action: AddressSaveAction) => Promise<IUserAddress[] \| void> \| IUserAddress[] \| void` | Called when the visitor submits the current form values. 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. |
+| `onCancel?: () => void`                                                                             | Called when the visitor cancels the current form or action. The callback has no payload.               |
+| `onDone?: () => void`                                                                               | Called when the visitor presses Done under the saved address. The callback has no payload.             |
+
+## Русский
+
+`AddressForm` создаёт или изменяет один адрес доставки. При изменении поля
+заполняются данными существующего адреса, а новая форма начинается пустой.
+Страна и регион обязательны до сохранения; название, город, улица и дом
+проверяются встроенной проверкой браузера. Дополнение к адресу, подъезд,
+домофон, этаж, квартира и индекс остаются необязательными. Поля не принимают
+больше символов, чем бэкенд: название — 32, город, улица и дополнение — 128,
+индекс — 64, дом, подъезд, домофон, этаж и квартира — 20.
+
+После монтирования `onLoadCountries` получает запрос `reload_customer_app` для
+`fUserAddress.country`. При изменении существующего адреса регионы запрашиваются
+после загрузки стран. Смена страны очищает регион, город, улицу, дом и индекс и
+передаёт запрос регионов. Смена региона очищает расположенные ниже адресные
+поля. Поиск региона вызывает `onSearchRegions`; варианты с одинаковым ID
+показываются один раз, а выбранный регион сохраняет подпись.
+
+После последнего изменения города или улицы компонент ненадолго ждёт и затем
+вызывает `onSuggestCity` или `onSuggestStreet`. Подсказки работают для страны,
+которая их поддерживает, и выбранного региона; для улицы также нужен город.
+Выбор города очищает улицу и применяет его индекс. Выбор улицы сохраняет
+текущий индекс, если в подсказке нового индекса нет.
+
+Если Application Load разрешает поиск по координатам, кнопка местоположения
+вызывает `onLocate`. Родитель получает разрешение браузера, вызывает метод
+координат и возвращает найденные страну, регион и адрес. Успешный `onSave`
+возвращает подтверждённый список адресов, после чего вызывается `onSaved`.
+
+После успешного сохранения форма показывает адрес так, как его сохранил бэкенд
+(первый адрес ответа): название, страну, регион, город, улицу, дом, индекс и
+заполненные дополнительные сведения. Плагин адресов страны может нормализовать
+город, улицу, дом, дополнение и индекс; поля, отличающиеся от отправленных,
+отмечены «уточнено», и уведомление просит их проверить, иначе зелёное
+уведомление подтверждает адрес. Фокус переходит на заголовок «Адрес сохранён».
+**Изменить** возвращает к форме с сохранёнными значениями, и следующее
+сохранение изменяет этот адрес (`address_edit`, в том числе после добавления).
+**Готово** вызывает `onDone`; родитель закрывает форму. Правка не снимает
+отметку основного адреса: у основного адреса флажок отмечен и недоступен, а
+подсказка предлагает воспользоваться меню адреса.
+
+`useOrionplaceAddressForm()` показывает те же локализованные тексты ошибок,
+что и другие фреймворки: у сбоя поиска региона, подсказок и местоположения свой
+текст, а при ошибке сохранения или загрузки стран выводятся сообщения полей от
+бэкенда или общий текст ошибки.
+
+### Свойства
+
+| Свойство                                                                                            | Назначение                                                                                             |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `address?: IUserAddress`                                                                            | Сохранённый адрес для редактирования; не передавайте его при создании адреса.                          |
+| `countries?: readonly IAddressCountryOption[]`                                                      | Страны, доступные в форме адреса.                                                                      |
+| `regions?: readonly IAddressRegion[]`                                                               | Регионы, доступные для выбранной страны адреса.                                                        |
+| `cities?: readonly IAddressCitySuggestion[]`                                                        | Подсказки городов для введённого адреса.                                                               |
+| `streets?: readonly IAddressSuggestion[]`                                                           | Подсказки улиц для выбранного города и введённого текста.                                              |
+| `pending?: boolean`                                                                                 | Показывает загрузку и блокирует повторные действия.                                                    |
+| `error?: string`                                                                                    | Ошибка запроса для покупателя; не передавайте её, если запрос не завершился ошибкой.                   |
+| `fieldErrors?: Readonly<Record<string, string>>`                                                    | Сообщения проверки по именам отправленных полей.                                                       |
+| `optionsPending?: boolean`                                                                          | Показывает выполнение запроса вариантов и блокирует повторные действия.                                |
+| `optionsError?: string`                                                                             | Ошибка запроса вариантов, которую видит покупатель.                                                    |
+| `regionPending?: boolean`                                                                           | Показывает выполнение запроса регионов и блокирует повторные действия.                                 |
+| `regionError?: string`                                                                              | Ошибка запроса регионов, которую видит покупатель.                                                     |
+| `hintPending?: "" \| "city" \| "street"`                                                            | Показывает выполнение запроса подсказок и блокирует повторные действия.                                |
+| `hintError?: string`                                                                                | Ошибка запроса подсказок, которую видит покупатель.                                                    |
+| `geoPending?: boolean`                                                                              | Показывает выполнение запроса координат и блокирует повторные действия.                                |
+| `geoError?: string`                                                                                 | Ошибка запроса координат, которую видит покупатель.                                                    |
+| `onLoadCountries?: (action: AddressCountriesAction) => Promise<void> \| void`                       | Вызывается, когда форме адреса нужен список стран. Данные обработчика указаны в его типе.              |
+| `onSearchRegions?: (request: IAddressRegionSearchRequest) => void`                                  | Вызывается, когда форма адреса ищет регионы. Данные обработчика указаны в его типе.                    |
+| `onSuggestCity?: (request: { country: number; region: number; search_string: string; }) => void`    | Вызывается, когда форма адреса запрашивает подсказки городов. Данные обработчика указаны в его типе.   |
+| `onSuggestStreet?: (request: IAddressSuggestionRequest) => void`                                    | Вызывается, когда форма адреса запрашивает подсказки улиц. Данные обработчика указаны в его типе.      |
+| `onLocate?: () => Promise<AddressLocationResult \| null> \| AddressLocationResult \| null`          | Вызывается, когда покупатель запрашивает координаты адреса. Обработчик не получает данные.             |
+| `onSave?: (action: AddressSaveAction) => Promise<IUserAddress[] \| void> \| IUserAddress[] \| void` | Вызывается, когда покупатель отправляет текущие значения формы. Данные обработчика указаны в его типе. |
+| `onSaved?: (addresses: IUserAddress[]) => void`                                                     | Вызывается, когда текущая запись успешно сохранена. Данные обработчика указаны в его типе.             |
+| `onCancel?: () => void`                                                                             | Вызывается, когда покупатель отменяет текущую форму или действие. Обработчик не получает данные.       |
+| `onDone?: () => void`                                                                               | Вызывается, когда покупатель нажал «Готово» под сохранённым адресом. Обработчик не получает данных.     |

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

@@ -0,0 +1,336 @@
+.form {
+  display: grid;
+  gap: 1.25rem;
+  min-width: 0;
+  padding: 1.25rem;
+  border: 1px solid var(--orionplace-border);
+  background: var(--orionplace-surface);
+  color: var(--orionplace-text);
+}
+
+.heading,
+.actions,
+.errorNotice {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: .75rem;
+}
+
+.heading {
+  justify-content: space-between;
+}
+
+/* As `op-feature-subtitle` in the other packages. */
+.heading h2,
+.details h3 {
+  margin: 0;
+  font-size: .875rem;
+  line-height: 1.25rem;
+  font-weight: 500;
+  letter-spacing: .08em;
+  text-transform: uppercase;
+}
+
+.fields {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 1rem;
+}
+
+.field,
+.details,
+.suggestionField {
+  display: grid;
+  align-content: start;
+  gap: .5rem;
+  min-width: 0;
+}
+
+.suggestionField {
+  gap: 1.25rem;
+}
+
+.field > span:first-child {
+  color: var(--orionplace-muted);
+  font-size: .75rem;
+  line-height: calc(1 / 0.75);
+  letter-spacing: .08em;
+  text-transform: uppercase;
+}
+
+.field input {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 2.75rem;
+  padding: .5rem .75rem;
+  border: 1px solid var(--orionplace-border);
+  border-radius: 0;
+  background: var(--orionplace-surface);
+  color: var(--orionplace-text);
+  font: inherit;
+  outline: none;
+}
+
+.field input:focus-visible {
+  border-color: var(--orionplace-text);
+}
+
+.field input[aria-invalid='true'] {
+  border-color: var(--orionplace-danger);
+}
+
+.field small,
+.required,
+.errorNotice {
+  color: var(--orionplace-danger);
+}
+
+.required {
+  letter-spacing: 0;
+}
+
+.details {
+  gap: 1.25rem;
+}
+
+.checkbox {
+  display: flex;
+  align-items: center;
+  gap: .5rem;
+}
+
+.checkbox input {
+  accent-color: var(--orionplace-accent);
+}
+
+/* As `op-feature-button` and `op-feature-primary` in the other packages;
+   the country select keeps its own look. */
+.form :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);
+  border-radius: 0;
+  background: transparent;
+  color: var(--orionplace-text);
+  font: inherit;
+  font-size: .75rem;
+  line-height: 1rem;
+  font-weight: 500;
+  letter-spacing: .08em;
+  text-transform: uppercase;
+  outline: none;
+  cursor: pointer;
+}
+
+.form :where(button:not([data-feature-part=OrionplaceSelect] *)):focus-visible {
+  background: var(--orionplace-hover);
+}
+
+@media (hover: hover) {
+  .form :where(button:not([data-feature-part=OrionplaceSelect] *)):hover {
+    background: var(--orionplace-hover);
+  }
+}
+
+.form :where(button:not([data-feature-part=OrionplaceSelect] *)):disabled {
+  cursor: default;
+  opacity: .6;
+}
+
+.form .primary {
+  border-color: var(--orionplace-accent);
+  background: var(--orionplace-accent);
+  color: var(--orionplace-surface);
+}
+
+.form .primary:focus-visible {
+  background: var(--orionplace-accent);
+  opacity: .85;
+}
+
+@media (hover: hover) {
+  .form .primary:hover {
+    background: var(--orionplace-accent);
+    opacity: .85;
+  }
+}
+
+.errorNotice {
+  margin: 0;
+  padding: .75rem 1rem;
+  border: 1px solid currentColor;
+}
+
+.hintError {
+  margin: 0;
+  color: var(--orionplace-muted);
+}
+
+.inputWithStatus {
+  position: relative;
+  display: block;
+}
+
+.inputWithStatus input {
+  padding-right: 2.5rem;
+}
+
+.spinner {
+  position: absolute;
+  top: 50%;
+  right: .75rem;
+  box-sizing: border-box;
+  width: 1rem;
+  height: 1rem;
+  margin-top: -.5rem;
+  border: 2px solid var(--orionplace-border);
+  border-top-color: var(--orionplace-text);
+  border-radius: 50%;
+  animation: address-spin .8s linear infinite;
+}
+
+.suggestions {
+  display: flex;
+  max-height: 14rem;
+  flex-direction: column;
+  gap: .25rem;
+  overflow-y: auto;
+}
+
+.suggestions button {
+  justify-content: flex-start;
+  text-align: left;
+}
+
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* The saved address: what the backend stored, with refined fields marked. */
+.saved {
+  container-type: inline-size;
+}
+
+.savedTitle {
+  margin: 0;
+  font-size: .875rem;
+  line-height: 1.25rem;
+  font-weight: 500;
+  letter-spacing: .08em;
+  text-transform: uppercase;
+  outline: none;
+}
+
+.savedNotice {
+  position: relative;
+  margin: 0;
+  padding: .75rem 1rem .75rem 44px;
+  border: 1px solid currentColor;
+  font-size: .875rem;
+  line-height: 1.5rem;
+  overflow-wrap: anywhere;
+}
+
+.savedNotice::before {
+  position: absolute;
+  top: .875rem;
+  left: .875rem;
+  width: 1.25rem;
+  height: 1.25rem;
+  content: "";
+  background: currentColor;
+  -webkit-mask: var(--op-notice-icon) center / contain no-repeat;
+  mask: var(--op-notice-icon) center / contain no-repeat;
+}
+
+.savedNotice[data-tone='success'] {
+  --op-notice-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='12' cy='12' r='9'/%3E%3Cpath d='m8 12.5 2.5 2.5L16 9.5'/%3E%3C/svg%3E");
+  background: var(--orionplace-success-surface);
+  color: var(--orionplace-success);
+}
+
+.savedNotice[data-tone='attention'] {
+  --op-notice-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M12 3.5 21.5 20h-19Z'/%3E%3Cpath d='M12 10v4.5m0 2.5h.01'/%3E%3C/svg%3E");
+  background: var(--orionplace-attention-surface);
+  color: var(--orionplace-attention);
+}
+
+.savedFields {
+  display: grid;
+  gap: .5rem;
+  margin: 0;
+  font-size: .875rem;
+  line-height: calc(1.25 / 0.875);
+}
+
+.savedFields > div {
+  display: grid;
+  gap: .25rem 1rem;
+}
+
+.savedFields dt {
+  color: var(--orionplace-muted);
+}
+
+.savedFields dd {
+  min-width: 0;
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+
+.refined {
+  margin-left: .5rem;
+  color: var(--orionplace-attention);
+  font-size: .75rem;
+  line-height: calc(1 / 0.75);
+  letter-spacing: .08em;
+  text-transform: uppercase;
+}
+
+.savedDefault {
+  margin: 0;
+  color: var(--orionplace-success);
+}
+
+.note {
+  margin: 0;
+  color: var(--orionplace-muted);
+  font-size: .875rem;
+  line-height: calc(1.25 / 0.875);
+}
+
+@container (min-width: 480px) {
+  .savedFields > div {
+    grid-template-columns: minmax(0, 12rem) minmax(0, 1fr);
+  }
+}
+
+@keyframes address-spin {
+  to { transform: rotate(360deg); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation: none;
+  }
+}
+
+/* A narrow page around the form (592px or less, the old 640px screen). */
+@container (max-width: 592px) {
+  .fields {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}