Address Forms

Important note: this component is not maintained by the ink team. If you have any questions, please reach out to the identity team in the #team-eng-profile Slack channel.

The ink team is proud to partner with the @carta/identity team to introduce the AddressAutocomplete component

The AddressAutocomplete component uses the Google Maps API and the Carta address service to create a full-stack address component which includes autocomplete functionality. All new address forms being added to the Carta platform should utilize this component, rather than building a form from scratch.

To use the AddressAutocomplete component in a FEP monorepo app, use the Frontend Platform team's FARSComponent to host the remote app within the monorepo app.

<FARSComponent
    environment="local"
    scope="identity"
    baseUrl="https://d1rvb1lpl8qv3z.cloudfront.net"
    module="AddressAutocomplete"
    props={{
        id: 'tax-address-validation',
        addressFields,
        setFields: (fields) => console.log('fields change`, fields),
    }}
/>

The snippet above is hosting the remote app from a test environment. Right now the baseUrl is hardcoded to get the app that is deployed on test environment. This can be changed to baseUrl={window.AWS_CLOUDFRONT_FEDERATED_BUNDLES_BASE}.

You can add devServer proxy in the webpack.config.ext.js file of the host monorepo app to route traffic to locally running address-service.

devServer: {
        proxy: {
            '/api/address-service/v1': {
                target: 'http://localhost:8053',
                pathRewrite: { '^/api/address-service/v1': '/v1/' },
            },
        },
    }

To use the AddressAutocomplete component on carta-web, utilize useState to instantiate address information in the following format:

const [fields, setFields] =
  useState <
  AddressFields >
  {
    streetAddress1: "",
    streetAddress2: "",
    streetAddress3: "",
    city: "",
    postalCode: "",
    province: "",
    countryCode: "",
    country: "",
    provinceCode: "",
    vettedBy: VettedBy.NO_ONE.toString(),
    isValid: false,
    locationId: "",
  }

Then, render the autocomplete app using FARSComponent and pass in the address object to the component:

<FARSComponent
    baseUrl={window.AWS_CLOUDFRONT_FEDERATED_BUNDLES_BASE}
    environment={window.CURRENT_ENV as Environment}
    scope="identity"
    module="AddressAutocomplete"
    props={{
        id: 'address-autocomplete-id',
        addressFields: autocompleteFields,
        setFields: setAutocompleteAddressFields,
        routerType: 'browser',
    }}
/>

The AddressAutocomplete component accepts the following props:

export type AddressFields = {
  /** Address field 1 */
  streetAddress1: string,
  /** Address field 2 */
  streetAddress2: string,
  /** Address field 3 */
  streetAddress3: string,
  /** City */
  city: string,
  /** Subdivision name eg: Alberta */
  province: string,
  /** Postalcode/ zip code */
  postalCode: string,
  /** Country long name eg: United States, Canada */
  country: string,
  /** Subdivision two letter iso code. eg: AB */
  provinceCode: string,
  /** Country three-letter iso code eg: USA, CAN */
  countryCode: string,
  /** Country two-letter iso code eg: US, CA */
  countryCodeAlpha2?: string,
  /** Random hash value returned from Address Service */
  locationId?: string | null,
  /** Flag determining if address is validate */
  isValid?: boolean,
  /** Value holder determining who validated the address */
  vettedBy?: string,
}

/** Unique identifier \*/
id: string;
/** Address fields that will be set by the component. Create a use state hook of type AddressFields and pass it down to the component. _/
addressFields: AddressFields;
/\*\* callback of type React dispatch. This will be used to assign the values to AddressFields. Create a usestate hook of type AddressFields and assign the setter to this prop. _/
setFields: React.Dispatch<React.SetStateAction<AddressFields>>;
/** Marks the element with a given id to make it easier to select it on tests \*/
'data-testid'?: string | number;
/** Set this prop if you'd like a countryCodeAlpha2 included in your response \*/
returnCountryCodeAlpha2?: boolean;
isFull?: boolean;
isStacked?: boolean;
/* Set this if you'd like to conditionally show field-level validation errors onChange of the address field */
validationCriteria?: AddressFieldsValidation

Validation criteria is input into Ink's Field error prop and input into the address component as shown below.

type ValidationFunction = (input: string) => string | false;

type AddressFieldsValidation = {
  streetAddress1?: ValidationFunction,
  streetAddress2?: ValidationFunction,
  streetAddress3?: ValidationFunction,
  city?: ValidationFunction,
  postalCode?: ValidationFunction,
  province?: ValidationFunction,
}

Example validation:

const postalCodeValidation = (postalCode: string) => {
    if (postalCode.length > 0 && isNaN(Number(postalCode)) {
        return "must be number";
    }
    if (postalCode.length < 5) {
        return "must be at least one char long";
    }
    return false;
}

const validationCriteria = {
    postalCode: postalCodeValidation
    ...
}

For real-world examples, see the following implementations of the AddressAutocomplete component: