orionplace-react 0.1.0 → 0.2.0

package/templates/components/orionplace/address/AddressForm.tsx

@@ -0,0 +1,827 @@
+'use client';
+
+import {
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type FormEvent,
+} from 'react';
+import {
+  useOrionplace,
+  useOrionplaceSelections,
+} from '@/providers/OrionplaceProvider';
+import { selectInit } from '@/stores/orionplace';
+import type {
+  IAddressCitySuggestion,
+} from '@/interfaces/orionplace/address/IAddressCitySuggestion';
+import type { IAddressCountryOption } from '@/interfaces/orionplace/address/IAddressEditor';
+import type {
+  IAddressLocationSuggestion,
+} from '@/interfaces/orionplace/address/IAddressLocationSuggestion';
+import type {
+  IAddressRegion,
+  IAddressRegionSearchRequest,
+} from '@/interfaces/orionplace/address/IAddressRegionSearch';
+import type {
+  IAddressSuggestion,
+  IAddressSuggestionRequest,
+} from '@/interfaces/orionplace/address/IAddressSuggestion';
+import type {
+  IUserAddress,
+  IUserAddressRequest,
+} from '@/interfaces/orionplace/address/IUserAddress';
+import { featureLabels } from '@/lib/orionplace/featureLabels';
+import {
+  addressCountryName,
+  addressRegionName,
+  uniqueAddressRegions,
+} from '@/lib/orionplace/addressPresentation';
+import {
+  refinedAddressFields,
+  type RefinableAddressField,
+} from '@/lib/orionplace/addressChanges';
+import { getAvailableNestedValueFromObject } from '@/lib/orionplace/presentation';
+import { OrionplaceSearchSelect } from '@/components/orionplace/shared/OrionplaceSearchSelect';
+import { OrionplaceSelect } from '@/components/orionplace/shared/OrionplaceSelect';
+import styles from './AddressForm.module.css';
+
+export interface AddressCountriesAction {
+  endpoint: 'reload_customer_app';
+  request: {
+    form: 'fUserAddress';
+    field_name: 'country';
+    filters: Record<string, never>;
+  };
+}
+
+export interface AddressSaveAction {
+  endpoint: 'address_add' | 'address_edit';
+  addressId?: number;
+  request: IUserAddressRequest;
+}
+
+export interface AddressLocationResult {
+  location: IAddressLocationSuggestion;
+  countryId: number;
+  region?: IAddressRegion;
+}
+
+export interface AddressFormProps {
+  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;
+}
+
+const emptyFields: IUserAddressRequest = {
+  address_label: '',
+  country: 0,
+  state: 0,
+  city: '',
+  line1: '',
+  line2: '',
+  house_number: '',
+  postcode: '',
+  entrance: '',
+  intercom: '',
+  floor: '',
+  apt_number: '',
+  is_default_for_shipping: false,
+};
+
+function initialFields(address?: IUserAddress): IUserAddressRequest {
+  return address ? {
+    address_label: address.address_label,
+    country: address.country?.id ?? 0,
+    state: address.state?.id ?? 0,
+    city: address.city,
+    line1: address.line1,
+    line2: address.line2,
+    house_number: address.house_number,
+    postcode: address.postcode,
+    entrance: address.entrance,
+    intercom: address.intercom,
+    floor: address.floor,
+    apt_number: address.apt_number,
+    is_default_for_shipping: address.is_default_for_shipping,
+  } : { ...emptyFields };
+}
+
+export function AddressForm({
+  address,
+  countries = [],
+  regions = [],
+  cities = [],
+  streets = [],
+  pending = false,
+  error = '',
+  fieldErrors = {},
+  optionsPending = false,
+  optionsError = '',
+  regionPending = false,
+  regionError = '',
+  hintPending = '',
+  hintError = '',
+  geoPending = false,
+  geoError = '',
+  onLoadCountries,
+  onSearchRegions,
+  onSuggestCity,
+  onSuggestStreet,
+  onLocate,
+  onSave,
+  onSaved,
+  onCancel,
+  onDone,
+}: AddressFormProps) {
+  const locale = useOrionplaceSelections((state) => state.localeCode);
+  const init = useOrionplace(selectInit);
+  const labels = featureLabels(locale);
+  const copy = labels.addresses;
+  const detailsId = useId();
+  const requested = useRef(false);
+  const mounted   = useRef(false);
+  const hintTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const savedHeading = useRef<HTMLHeadingElement>(null);
+  const [fields, setFields] = useState(() => initialFields(address));
+  // The address as the last save returned it; later saves edit it.
+  const [saved, setSaved] = useState(address);
+  const [reviewing, setReviewing] = useState(false);
+  const [refined, setRefined] = useState<RefinableAddressField[]>([]);
+  const [selectedRegion, setSelectedRegion] = useState(address?.state ?? null);
+  const [activeSuggestions, setActiveSuggestions] = useState<
+    '' | 'city' | 'street'
+  >('');
+  const busy = pending || geoPending;
+  const country = countries.find((item) => item.value === fields.country);
+  const suggestionsEnabled = Boolean(country?.suggestions && fields.state);
+  const countryOptions = {
+    '0': copy.chooseCountry,
+    ...Object.fromEntries(countries.map((item) => [
+      String(item.value),
+      getAvailableNestedValueFromObject(
+        item.locale,
+        locale,
+        'printable_name',
+      ) || item.iso_3166_1_a2,
+    ])),
+  };
+  const countryCodes = Object.fromEntries(countries.map((item) => [
+    String(item.value),
+    item.iso_3166_1_a2,
+  ]));
+  const regionOptions = uniqueAddressRegions(regions).map((region) => ({
+    value: String(region.id),
+    label: addressRegionName(region, locale),
+  }));
+  // Editing never clears the default mark; the address menu does.
+  const defaultKept = Boolean(saved?.is_default_for_shipping);
+  // No delivery to the chosen country: the address can be saved, but the
+  // backend refuses it as the default.
+  const noShipping = country !== undefined && !country.is_shipping_country;
+
+  // `mounted` is a ref: React runs effects twice in development, and the
+  // countries requested by the first run must still bring the regions.
+  useEffect(() => {
+    mounted.current = true;
+    if (!requested.current) {
+      requested.current = true;
+      void loadCountries().then(() => {
+        if (mounted.current && fields.country) {
+          requestRegions(fields.country);
+        }
+      }).catch(() => undefined);
+    }
+    return () => {
+      mounted.current = false;
+      clearTimeout(hintTimer.current);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (reviewing) {
+      savedHeading.current?.focus();
+    }
+  }, [reviewing]);
+
+  function countriesAction(): AddressCountriesAction {
+    return {
+      endpoint: 'reload_customer_app',
+      request: {
+        form: 'fUserAddress',
+        field_name: 'country',
+        filters: {},
+      },
+    };
+  }
+
+  async function loadCountries() {
+    await onLoadCountries?.(countriesAction());
+  }
+
+  function requestRegions(countryId: number, query = '') {
+    onSearchRegions?.({
+      filters: {
+        country: countryId,
+        region_name: query,
+      },
+    });
+  }
+
+  function update<Key extends keyof IUserAddressRequest>(
+    name: Key,
+    value: IUserAddressRequest[Key],
+  ) {
+    setFields((current) => ({ ...current, [name]: value }));
+  }
+
+  function selectCountry(value: string) {
+    clearTimeout(hintTimer.current);
+    setActiveSuggestions('');
+    const countryId = Number(value);
+    setSelectedRegion(null);
+    setFields((current) => ({
+      ...current,
+      country: countryId,
+      state: 0,
+      city: '',
+      line1: '',
+      house_number: '',
+      postcode: '',
+    }));
+    if (countryId) {
+      requestRegions(countryId);
+    }
+  }
+
+  function selectRegion(value: string) {
+    clearTimeout(hintTimer.current);
+    setActiveSuggestions('');
+    const regionId = Number(value);
+    setSelectedRegion(regions.find((item) => item.id === regionId) ?? null);
+    setFields((current) => ({
+      ...current,
+      state: regionId,
+      city: '',
+      line1: '',
+      house_number: '',
+      postcode: '',
+    }));
+  }
+
+  function scheduleSuggestion(mode: 'city' | 'street', value: string) {
+    clearTimeout(hintTimer.current);
+    setActiveSuggestions('');
+    if (
+      !suggestionsEnabled ||
+      value.trim().length < 2 ||
+      (mode === 'street' && !fields.city)
+    ) {
+      return;
+    }
+    setActiveSuggestions(mode);
+    hintTimer.current = setTimeout(() => {
+      if (mode === 'city') {
+        onSuggestCity?.({
+          country: fields.country,
+          region: fields.state,
+          search_string: value,
+        });
+      } else {
+        onSuggestStreet?.({
+          country: fields.country,
+          region: fields.state,
+          city: fields.city,
+          address_string: value,
+        });
+      }
+    }, 300);
+  }
+
+  function changeCity(event: ChangeEvent<HTMLInputElement>) {
+    const value = event.target.value;
+    update('city', value);
+    scheduleSuggestion('city', value);
+  }
+
+  function changeStreet(event: ChangeEvent<HTMLInputElement>) {
+    const value = event.target.value;
+    update('line1', value);
+    scheduleSuggestion('street', value);
+  }
+
+  async function locate() {
+    if (!onLocate || busy) {
+      return;
+    }
+    try {
+      const result = await onLocate();
+      if (!result) {
+        return;
+      }
+      setSelectedRegion(result.region ?? null);
+      setActiveSuggestions('');
+      setFields((current) => ({
+        ...current,
+        country: result.countryId,
+        state: result.region?.id ?? 0,
+        city: result.location.city ?? '',
+        line1: result.location.street ?? '',
+        house_number: result.location.house ?? '',
+        postcode: result.location.postal_code ?? '',
+      }));
+    } catch {
+      return;
+    }
+  }
+
+  async function save(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!onSave || !fields.country || !fields.state || busy) {
+      return;
+    }
+    const sent = {
+      ...fields,
+      is_default_for_shipping: Boolean(fields.is_default_for_shipping) && !noShipping,
+    };
+    try {
+      const result = await onSave({
+        endpoint: saved ? 'address_edit' : 'address_add',
+        addressId: saved?.id,
+        request: sent,
+      });
+      const value = result?.[0];
+      // The form then shows the address as the backend saved it: an address
+      // plugin may have normalized city, street, house, second line and
+      // postcode.
+      if (value) {
+        clearTimeout(hintTimer.current);
+        setActiveSuggestions('');
+        setSaved(value);
+        setRefined(refinedAddressFields(sent, value));
+        setSelectedRegion(value.state);
+        setFields(initialFields(value));
+        setReviewing(true);
+      }
+      if (result) {
+        onSaved?.(result);
+      }
+    } catch {
+      return;
+    }
+  }
+
+  // «Edit» returns from the saved address to the form with its saved values.
+  function edit() {
+    setReviewing(false);
+    setRefined([]);
+  }
+
+  if (reviewing && saved) {
+    const rows = ([
+      ['address_label', copy.label, saved.address_label],
+      ['country', copy.country, addressCountryName(saved.country, locale)],
+      [
+        'state',
+        copy.region,
+        saved.state ? addressRegionName(saved.state, locale) : '',
+      ],
+      ['city', copy.city, saved.city],
+      ['line1', copy.street, saved.line1],
+      ['house_number', copy.house, saved.house_number],
+      ['postcode', copy.postcode, saved.postcode],
+      ['line2', copy.line2, saved.line2],
+      ['entrance', copy.entrance, saved.entrance],
+      ['intercom', copy.intercom, saved.intercom],
+      ['floor', copy.floor, saved.floor],
+      ['apt_number', copy.apartment, saved.apt_number],
+    ] as const)
+      .map(([name, label, text]) => ({
+        name,
+        label,
+        text,
+        refined: (refined as readonly string[]).includes(name),
+      }))
+      .filter((row) => row.text || row.refined);
+    return (
+      <section
+        className={`${styles.form} ${styles.saved}`}
+        data-feature-part="AddressForm"
+        data-address-saved
+      >
+        <h2
+          ref={savedHeading}
+          className={styles.savedTitle}
+          tabIndex={-1}
+        >
+          {copy.savedTitle}
+        </h2>
+        <p
+          className={styles.savedNotice}
+          data-tone={refined.length ? 'attention' : 'success'}
+          role="status"
+        >
+          {refined.length ? copy.savedRefined : copy.savedAsSent}
+        </p>
+        <dl className={styles.savedFields}>
+          {rows.map((row) => (
+            <div
+              key={row.name}
+              data-address-saved-field={row.name}
+              data-address-refined={row.refined || undefined}
+            >
+              <dt>{row.label}</dt>
+              <dd>
+                {row.text || '—'}
+                {row.refined ? (
+                  <span className={styles.refined}>{copy.refined}</span>
+                ) : null}
+              </dd>
+            </div>
+          ))}
+        </dl>
+        {saved.is_default_for_shipping ? (
+          <p className={styles.savedDefault}>{copy.default}</p>
+        ) : null}
+        <div className={styles.actions}>
+          <button
+            type="button"
+            className={styles.primary}
+            data-address-saved-done
+            onClick={() => onDone?.()}
+          >
+            {copy.done}
+          </button>
+          <button
+            type="button"
+            data-address-saved-edit
+            onClick={edit}
+          >
+            {labels.edit}
+          </button>
+        </div>
+      </section>
+    );
+  }
+
+  return (
+    <form
+      className={styles.form}
+      aria-busy={busy}
+      data-feature-part="AddressForm"
+      onSubmit={save}
+    >
+      <div className={styles.heading}>
+        <h2>{saved ? copy.edit : copy.add}</h2>
+        {init?.geo_location_enabled ? (
+          <button
+            type="button"
+            disabled={busy || !countries.length}
+            data-address-locate
+            onClick={() => void locate()}
+          >
+            {geoPending ? labels.loading : copy.locate}
+          </button>
+        ) : null}
+      </div>
+      {error || geoError ? (
+        <p className={styles.errorNotice} role="alert">{error || geoError}</p>
+      ) : null}
+      {optionsError ? (
+        <div className={styles.errorNotice} role="alert">
+          <span>{optionsError}</span>
+          <button
+            type="button"
+            onClick={() => void loadCountries()}
+          >
+            {labels.retry}
+          </button>
+        </div>
+      ) : null}
+      <TextField
+        label={copy.label}
+        name="address_label"
+        value={fields.address_label}
+        required
+        minLength={3}
+        maxLength={32}
+        disabled={busy}
+        error={fieldErrors.address_label}
+        onChange={(value) => update('address_label', value)}
+      />
+      <div className={styles.fields}>
+        <OrionplaceSelect
+          value={String(fields.country)}
+          options={countryOptions}
+          countryCodes={countryCodes}
+          label={copy.country}
+          disabled={busy || optionsPending}
+          required
+          onValueChange={selectCountry}
+        />
+        <OrionplaceSearchSelect
+          value={fields.state ? String(fields.state) : ''}
+          options={regionOptions}
+          selectedLabel={selectedRegion
+            ? addressRegionName(selectedRegion, locale)
+            : ''}
+          label={copy.region}
+          placeholder={copy.findRegion}
+          loadingLabel={labels.loading}
+          emptyLabel={labels.noMatches}
+          retryLabel={labels.retry}
+          pending={regionPending}
+          error={regionError}
+          disabled={busy || !fields.country}
+          required
+          onSearch={(query) => onSearchRegions?.({
+            filters: {
+              country: fields.country,
+              region_name: query,
+            },
+          })}
+          onValueChange={selectRegion}
+        />
+        <SuggestionField
+          label={copy.city}
+          name="city"
+          value={fields.city}
+          maxLength={128}
+          suggestions={activeSuggestions === 'city'
+            ? cities.map((item) => ({ label: item.city, value: item }))
+            : []}
+          pending={hintPending === 'city'}
+          disabled={busy}
+          autoComplete="address-level2"
+          error={fieldErrors.city}
+          onChange={changeCity}
+          onSelect={(item) => {
+            clearTimeout(hintTimer.current);
+            setActiveSuggestions('');
+            setFields((current) => ({
+              ...current,
+              city: item.city,
+              line1: '',
+              postcode: item.postal_code ?? '',
+            }));
+          }}
+        />
+        <SuggestionField
+          label={copy.street}
+          name="line1"
+          value={fields.line1}
+          maxLength={128}
+          suggestions={activeSuggestions === 'street'
+            ? streets.map((item) => ({ label: item.street, value: item }))
+            : []}
+          pending={hintPending === 'street'}
+          disabled={busy}
+          autoComplete="address-line1"
+          error={fieldErrors.line1}
+          onChange={changeStreet}
+          onSelect={(item) => {
+            clearTimeout(hintTimer.current);
+            setActiveSuggestions('');
+            setFields((current) => ({
+              ...current,
+              line1: item.street,
+              postcode: item.postal_code ?? current.postcode,
+            }));
+          }}
+        />
+        <TextField
+          label={copy.house}
+          name="house_number"
+          value={fields.house_number}
+          required
+          maxLength={20}
+          disabled={busy}
+          error={fieldErrors.house_number}
+          onChange={(value) => update('house_number', value)}
+        />
+        <TextField
+          label={copy.postcode}
+          name="postcode"
+          value={fields.postcode ?? ''}
+          maxLength={64}
+          autoComplete="postal-code"
+          disabled={busy}
+          error={fieldErrors.postcode}
+          onChange={(value) => update('postcode', value)}
+        />
+      </div>
+      <span className={styles.srOnly} role="status">
+        {hintPending ? copy.suggestionsLoading : ''}
+      </span>
+      {hintError ? <p className={styles.hintError} role="status">{hintError}</p> : null}
+      <section className={styles.details} aria-labelledby={detailsId}>
+        <h3 id={detailsId}>{copy.details}</h3>
+        <div className={styles.fields}>
+          {([
+            ['line2', copy.line2, 128],
+            ['entrance', copy.entrance, 20],
+            ['intercom', copy.intercom, 20],
+            ['floor', copy.floor, 20],
+            ['apt_number', copy.apartment, 20],
+          ] as const).map(([name, label, maxLength]) => (
+            <TextField
+              key={name}
+              label={label}
+              name={name}
+              value={String(fields[name] ?? '')}
+              maxLength={maxLength}
+              disabled={busy}
+              error={fieldErrors[name]}
+              onChange={(value) => update(name, value)}
+            />
+          ))}
+        </div>
+      </section>
+      <label className={styles.checkbox}>
+        <input
+          type="checkbox"
+          checked={Boolean(fields.is_default_for_shipping) && !noShipping}
+          disabled={busy || defaultKept || noShipping}
+          onChange={(event) => update(
+            'is_default_for_shipping',
+            event.target.checked,
+          )}
+        />
+        <span>{copy.default}</span>
+      </label>
+      {noShipping ? (
+        <p
+          className={styles.note}
+          data-address-no-shipping
+        >
+          {copy.noShippingDefault}
+        </p>
+      ) : defaultKept ? (
+        <p className={styles.note}>{copy.defaultKept}</p>
+      ) : null}
+      <div className={styles.actions}>
+        <button
+          type="submit"
+          className={styles.primary}
+          disabled={busy || !fields.country || !fields.state}
+        >
+          {busy ? labels.loading : labels.save}
+        </button>
+        <button type="button" disabled={busy} onClick={() => onCancel?.()}>
+          {labels.cancel}
+        </button>
+      </div>
+    </form>
+  );
+}
+
+interface TextFieldProps {
+  label: string;
+  name: string;
+  value: string;
+  required?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  autoComplete?: string;
+  disabled?: boolean;
+  error?: string;
+  onChange: (value: string) => void;
+}
+
+function TextField({
+  label,
+  name,
+  value,
+  required = false,
+  minLength,
+  maxLength,
+  autoComplete,
+  disabled = false,
+  error,
+  onChange,
+}: TextFieldProps) {
+  return (
+    <label className={styles.field}>
+      <span>{label} {required ? <Required /> : null}</span>
+      <input
+        name={name}
+        value={value}
+        required={required}
+        minLength={minLength}
+        maxLength={maxLength}
+        autoComplete={autoComplete}
+        disabled={disabled}
+        aria-invalid={Boolean(error)}
+        onChange={(event) => onChange(event.target.value)}
+      />
+      {/* The form's notice announces the error; the field only shows it. */}
+      {error ? <small>{error}</small> : null}
+    </label>
+  );
+}
+
+interface SuggestionFieldProps<Value> {
+  label: string;
+  name: string;
+  value: string;
+  maxLength: number;
+  suggestions: { label: string; value: Value }[];
+  pending: boolean;
+  disabled: boolean;
+  autoComplete?: string;
+  error?: string;
+  onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+  onSelect: (value: Value) => void;
+}
+
+function SuggestionField<Value>({
+  label,
+  name,
+  value,
+  maxLength,
+  suggestions,
+  pending,
+  disabled,
+  autoComplete,
+  error,
+  onChange,
+  onSelect,
+}: SuggestionFieldProps<Value>) {
+  return (
+    <div className={styles.suggestionField}>
+      <label className={styles.field}>
+        <span>{label} <Required /></span>
+        <span className={styles.inputWithStatus}>
+          <input
+            name={name}
+            value={value}
+            required
+            maxLength={maxLength}
+            disabled={disabled}
+            autoComplete={autoComplete}
+            aria-invalid={Boolean(error)}
+            aria-busy={pending || undefined}
+            onChange={onChange}
+          />
+          {pending ? (
+            <span
+              className={styles.spinner}
+              data-address-hint-spinner={name === 'city' ? 'city' : 'street'}
+              aria-hidden="true"
+            />
+          ) : null}
+        </span>
+        {error ? <small>{error}</small> : null}
+      </label>
+      {suggestions.length ? (
+        <div className={styles.suggestions} aria-label={label}>
+          {suggestions.map((item) => (
+            <button
+              key={item.label}
+              type="button"
+              disabled={disabled}
+              onClick={() => onSelect(item.value)}
+            >
+              {item.label}
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function Required() {
+  return <span className={styles.required} aria-hidden="true">*</span>;
+}