@bcrs-shared-components/base-address 2.0.11 → 3.0.0

package/factories/address-factory.ts

@@ -0,0 +1,215 @@
+/* eslint-disable */
+import { computed, reactive, ref, Ref } from 'vue-demi'
+import { uniqueId } from 'lodash'
+
+import { AddressIF, SchemaIF } from '@bcrs-shared-components/interfaces'
+
+export function useAddress (address: Ref<AddressIF>, schema: SchemaIF) {
+  const addressLocal = address
+  /** The Address Country, to simplify the template and so we can watch it directly. */
+  const country = computed((): string => {
+    return addressLocal.value.country
+  })
+  const schemaLocal = ref(schema)
+  const isSchemaRequired = (prop: string): boolean => {
+    if (!schemaLocal || !schemaLocal.value[prop]) return false
+
+    // check for any rule that does not allow an empty string
+    for (let index in schemaLocal.value[prop]) {
+      if (schemaLocal.value[prop][index]('') !== true) return true
+    }
+    return false
+  }
+  const labels = {
+    /** The Street Address Additional label with 'optional' as needed. */
+    streetAdditionalLabel: computed((): string => {
+      return 'Address Line 2' + (isSchemaRequired('streetAdditional') ? '' : ' (Optional)')
+    }),
+    /** The Street Address label with 'optional' as needed. */
+    streetLabel: computed((): string => {
+      return 'Address Line 1' + (isSchemaRequired('street') ? '' : ' (Optional)')
+    }),
+    /** The Address City label with 'optional' as needed. */
+    cityLabel: computed((): string => {
+      return 'City' + (isSchemaRequired('city') ? '' : ' (Optional)')
+    }),
+    /** The Address Region label with 'optional' as needed. */
+    regionLabel: computed((): string => {
+      let label: string
+      let required = isSchemaRequired('region')
+
+      // NB: make region required for Canada and USA
+      if (addressLocal.value.country === 'CA') {
+        label = 'Province'
+        required = true
+      } else if (addressLocal.value.country === 'US') {
+        label = 'State'
+        required = true
+      } else {
+        label = 'Region'
+      }
+      return label + (required ? '' : ' (Optional)')
+    }),
+    /** The Postal Code label with 'optional' as needed. */
+    postalCodeLabel: computed((): string => {
+      let label: string
+      if (addressLocal.value.country === 'US') {
+        label = 'Zip Code'
+      } else {
+        label = 'Postal Code'
+      }
+      return label + (isSchemaRequired('postalCode') ? '' : ' (Optional)')
+    }),
+    /** The Address Country label with 'optional' as needed. */
+    countryLabel: computed((): string => {
+      return 'Country' + (isSchemaRequired('country') ? '' : ' (Optional)')
+    }),
+    /** The Delivery Instructions label with 'optional' as needed. */
+    deliveryInstructionsLabel: computed((): string => {
+      return 'Delivery Instructions' + (isSchemaRequired('deliveryInstructions') ? '' : ' (Optional)')
+    })
+  }
+  return {
+    addressLocal,
+    country,
+    schemaLocal,
+    isSchemaRequired,
+    labels
+  }
+}
+
+export function useAddressComplete (addressLocal: Ref<AddressIF>) {
+  const combineLines = (line1: string, line2: string) => {
+    if (!line1) return line2
+    if (!line2) return line1
+    return line1 + '\n' + line2
+  }
+  /**
+   * Callback to update the address data after the user chooses a suggested address.
+   * @param address the data object returned by the AddressComplete Retrieve API
+   */
+  const addressCompletePopulate = (addressComplete: object): void => {
+    addressLocal.value.streetAddress = addressComplete['Line1'] || 'N/A'
+    // Combine extra address lines into Street Address Additional field.
+    addressLocal.value.streetAddressAdditional = combineLines(
+      combineLines(addressComplete['Line2'], addressComplete['Line3']),
+      combineLines(addressComplete['Line4'], addressComplete['Line5'])
+    )
+    addressLocal.value.city = addressComplete['City']
+    if (useCountryRegions(addressComplete['CountryIso2'])) {
+      // In this case, v-select will map known province code to province name
+      // or v-select will be blank and user will have to select a known item.
+      addressLocal.value.region = addressComplete['ProvinceCode']
+    } else {
+      // In this case, v-text-input will allow manual entry but province info is probably too long
+      // so set region to null and add province name to the Street Address Additional field.
+      // If length is excessive, user will have to fix it.
+      addressLocal.value.region = ''
+      addressLocal.value.streetAdditional = combineLines(
+        addressLocal.value.streetAdditional, addressComplete['ProvinceName']
+      )
+    }
+    addressLocal.value.postalCode = addressComplete['PostalCode']
+    addressLocal.value.country = addressComplete['CountryIso2']
+  }
+  const uniqueIds = reactive({
+    /** A unique id for this instance of this component. */
+    uniqueId: uniqueId(),
+    /** A unique id for the Street Address input. */
+    streetId: computed((): string => {
+      return `street-address-${uniqueIds.uniqueId}`
+    }),
+    /** A unique id for the Address Country input. */
+    countryId: computed((): string => {
+      return `address-country-${uniqueIds.uniqueId}`
+    })
+  })
+  /**
+   * Creates the AddressComplete object for this instance of the component.
+   * @param pca the Postal Code Anywhere object provided by AddressComplete
+   * @param key the key for the Canada Post account that is to be charged for lookups
+   * @returns an object that is a pca.Address instance
+   */
+  const createAddressComplete = (pca: any, key: string): object => {
+    // Set up the two fields that AddressComplete will use for input.
+    // Ref: https://www.canadapost.ca/pca/support/guides/advanced
+    // Note: Use special field for country, which user can't click, and which AC will overwrite
+    //       but that we don't care about.
+    const fields = [
+      { element: uniqueIds.streetId, field: 'Line1', mode: pca.fieldMode.SEARCH },
+      { element: uniqueIds.countryId, field: 'CountryName', mode: pca.fieldMode.COUNTRY }
+    ]
+    const options = { key }
+
+    const addressComplete = new pca.Address(fields, options)
+
+    // The documentation contains sample load/populate callback code that doesn't work, but this will. The side effect
+    // is that it breaks the autofill functionality provided by the library, but we really don't want the library
+    // altering the DOM because Vue is already doing so, and the two don't play well together.
+    addressComplete.listen('populate', addressCompletePopulate)
+
+    return addressComplete
+  }
+  /** Enables AddressComplete for this instance of the address. */
+  const enableAddressComplete = (): void => {
+    // If you want to use this component with the Canada Post AddressComplete service:
+    // 1. The AddressComplete JavaScript script (and stylesheet) must be loaded.
+    // 2. Your AddressComplete account key must be defined.
+    const pca = window['pca']
+    const key = window['addressCompleteKey']
+    if (!pca || !key) {
+      // eslint-disable-next-line no-console
+      console.log('AddressComplete not initialized due to missing script and/or key')
+      return
+    }
+
+    // Destroy the old object if it exists, and create a new one.
+    if (window['currentAddressComplete']) {
+      window['currentAddressComplete'].destroy()
+    }
+    window['currentAddressComplete'] = createAddressComplete(pca, key)
+  }
+  return {
+    addressCompletePopulate,
+    createAddressComplete,
+    enableAddressComplete,
+    uniqueIds
+  }
+}
+
+/**
+ * Determines whether to use a country's known regions (ie, provinces/states).
+ * @param code the short code of the country
+ * @returns whether to use v-select (true) or v-text-field (false) for input
+ */
+export function useCountryRegions (code: string): boolean {
+  return (code === 'CA' || code === 'US')
+}
+
+export function formatAddress (address: AddressIF): AddressIF {
+  address.postalCode = address.postalCode?.toUpperCase() || ''
+  if (address.country === 'CA') {
+    address.postalCode = address.postalCode.replace('-', ' ')
+    if (address.postalCode.length > 4 && address.postalCode[3] !== ' ') {
+      address.postalCode = address.postalCode.slice(0, 3) + ' ' + address.postalCode.slice(3,)
+    }
+  }
+  return {
+    country: address.country?.trim(),
+    street: address.street?.trim(),
+    streetAdditional: address.streetAdditional?.trim(),
+    city: address.city?.trim(),
+    region: address.region?.trim(),
+    postalCode: address.postalCode?.trim(),
+    deliveryInstructions: address.deliveryInstructions?.trim()
+  }
+}
+
+export function checkAddress (address: AddressIF, schema: SchemaIF): AddressIF {
+  for(var addressProperty in schema) {
+    if (!address[addressProperty]) {
+      address[addressProperty] = ''
+    }
+  }
+  return address
+}

package/factories/countries-provinces-factory.ts

@@ -0,0 +1,78 @@
+import countriesData from 'country-list/data.json'
+import provincesData from 'provinces/provinces.json'
+
+window['countries'] = window['countries'] || countriesData.sort((a, b) =>
+  (a.name < b.name) ? -1 : (a.name > b.name) ? 1 : 0)
+
+window['provinces'] = window['provinces'] || provincesData.sort((a, b) =>
+  (a.name < b.name) ? -1 : (a.name > b.name) ? 1 : 0)
+
+// global caching to improve performance when called multiple times
+window['countryNameCache'] = {}
+window['countryRegionsCache'] = {}
+
+/**
+ * Factory that allows VM access to useful country/province data and functions.
+ * @link https://www.npmjs.com/package/country-list
+ * @lint https://www.npmjs.com/package/provinces
+ */
+export function useCountriesProvinces () {
+  /**
+   * Helper function to return a list of countries.
+   * @returns An array of country objects, sorted alphabetically.
+   */
+  const getCountries = (naOnly = false): Array<object> => {
+    let countries = []
+    countries.push({ code: 'CA', name: 'Canada' })
+    countries.push({ code: 'US', name: 'United States' })
+    if (!naOnly) {
+      // name is set this way to ensure the divider is there in the search when CA/US are not the only options
+      countries.push({ code: '0', name: 'Can.nada. United States .Of.America', divider: true })
+      countries = countries.concat(window['countries'])
+    }
+    return countries
+  }
+  /**
+   * Helper function to return a country's name.
+   * @param code The short code of the country.
+   * @returns The long name of the country.
+   */
+  const getCountryName = (code: string): string => {
+    if (!code) return null
+    if (window['countryNameCache'][code]) return window['countryNameCache'][code]
+    const country = window['countries'].find(c => c.code === code)
+    const result = country ? country.name : null
+    window['countryNameCache'][code] = result
+    return result
+  }
+  /**
+   * Helper function to return a country's list of provinces.
+   * @param code The short code of the country.
+   * @param overrideDefault A flag to bypass manual defaults.
+   * @returns An array of province objects, sorted alphabetically.
+   */
+  const getCountryRegions = (code: string, overrideDefault = false): Array<object> => {
+    if (!code) return []
+    if (window['countryRegionsCache'][code]) return window['countryRegionsCache'][code]
+    let regions = []
+    if (code === 'CA' && !overrideDefault) {
+      regions.push({ name: 'British Columbia', short: 'BC' })
+      // name is set this way to ensure the divider is there in the search when BC is not the only option
+      regions.push({ code: '0', name: 'Br.it.is.h.Co.l.u.m.b.ia', divider: true })
+    }
+    const result = window['provinces']
+      .filter(p => p.country === code)
+      .map(p => ({
+        name: p.english || p.name,
+        short: (p.short && p.short.length <= 2) ? p.short : '--'
+      }))
+    regions = regions.concat(result)
+    window['countryRegionsCache'][code] = regions
+    return regions
+  }
+  return {
+    getCountries,
+    getCountryName,
+    getCountryRegions
+  }
+}

package/factories/index.ts

@@ -0,0 +1,3 @@
+export { formatAddress, useAddress, useAddressComplete, useCountryRegions } from './address-factory'
+export { useCountriesProvinces } from './countries-provinces-factory'
+export { baseRules, spaceRules, useBaseValidations } from './validation-factory'

package/factories/validation-factory.ts

@@ -0,0 +1,42 @@
+import { ref } from 'vue-demi'
+
+import { AddressValidationRules } from '@bcrs-shared-components/enums'
+
+/* Sets up form validation functions */
+export function useBaseValidations () {
+  /* this variable must be named the same as your ref=___ in your form */
+  const addressForm = ref(null)
+  const resetValidation = () => {
+    addressForm.value?.resetValidation()
+  }
+  const validate = () => {
+    addressForm.value?.validate()
+  }
+  return { addressForm, resetValidation, validate }
+}
+
+/* Rules used in most schemas */
+export const baseRules = {
+  [AddressValidationRules.BC]: (v: string) => v === 'BC' || v === 'British Columbia' || 'Address must be in BC',
+  [AddressValidationRules.CANADA]: (v: string) => v === 'CA' || 'Address must be in Canada',
+  [AddressValidationRules.MAX_LENGTH]: (max: number) => {
+    return (v: string) => (v || '').length <= max || `Maximum ${max} characters`
+  },
+  [AddressValidationRules.MIN_LENGTH]: (min: number) => {
+    return (v: string) => (v || '').length >= min || `Minimum ${min} characters`
+  },
+  [AddressValidationRules.POSTAL_CODE]: (v: string) => (
+    /^\s*[ABCEGHJ-NPRSTVXY]\d[ABCEGHJ-NPRSTV-Z][\s-]?\d[ABCEGHJ-NPRSTV-Z]\d\s*$/i.test(v) ||
+    'Must be a valid postal code'
+  ),
+  [AddressValidationRules.REQUIRED]: (v: string) => v?.length > 0 || 'This field is required',
+  [AddressValidationRules.ZIP_CODE]: (v: string) => (
+    /^\s*[0-9]{5}([\s-]?[0-9]{4})?\s*$/i.test(v) ||
+    'Must be a valid zip code'
+  )
+}
+
+/* Array of validation rules used by input elements to prevent extra whitespace. */
+export const spaceRules = [
+  (v: string) => !/^\s/g.test(v) || 'Invalid spaces' // leading spaces
+]

package/factories/vuelidate-validation-factory.ts

@@ -0,0 +1,118 @@
+/* FUTURE:
+ * Delete this if we decide not to move forward with vuelidate
+ * Fix it to work otherwise
+ */
+import { computed, Ref, reactive } from 'vue-demi'
+
+import { AddressIF, SchemaIF } from '@bcrs-shared-components/interfaces'
+
+import useVuelidate from '@vuelidate/core'
+
+export function useValidations (schema: Ref<SchemaIF>, address: Ref<AddressIF>) {
+  const validations = reactive({ addressLocal: schema.value })
+  const $v = useVuelidate(validations, reactive({ addressLocal: address.value }))
+
+  /**
+   * Misc Vuetify rules.
+   * @param prop The name of the property object to validate.
+   * @param key The name of the property key (field) to validate.
+   * @returns True if the rule passes, otherwise an error string.
+   */
+  const vuetifyRules = {
+    requiredRule: (prop: string, key: string): boolean | string => {
+      return Boolean($v.value[prop] && !$v.value[prop][key].required.$invalid) || 'This field is required'
+    },
+    minLengthRule: (prop: string, key: string): boolean | string => {
+      const min = validations.addressLocal[key].max
+      const msg = min ? `Minimum length is ${min}` : 'Text is below minimum length'
+      return Boolean($v.value[prop] && !$v.value[prop][key].minLength.$invalid) || msg
+    },
+    maxLengthRule: (prop: string, key: string): boolean | string => {
+      const max = validations.addressLocal[key].max
+      const msg = max ? `Maximum length is ${max}` : 'Text is over maximum length'
+      return Boolean($v.value[prop] && !$v.value[prop][key].maxLength.$invalid) || msg
+    },
+    // FUTURE: generalize this rule to take a validation parameter (ie, 'CA')
+    isCanadaRule: (prop: string, key: string): boolean | string => {
+      return Boolean($v.value[prop] && !$v.value[prop][key].isCanada.$invalid) || 'Address must be in Canada'
+    },
+    // FUTURE: generalize this rule to take a validation parameter (ie, 'BC')
+    isBCRule: (prop: string, key: string): boolean | string => {
+      return Boolean($v.value[prop] && !$v.value[prop][key].isBC.$invalid) || 'Address must be in BC'
+    }
+  }
+
+  /**
+   * Creates a Vuetify rules object from the Vuelidate state.
+   * @param model The name of the model we are validating.
+   * @returns A Vuetify rules object.
+   */
+  const createVuetifyRulesObject = (model: string): { [attr: string]: Array<Function> } => {
+    const obj = {
+      street: [],
+      streetAdditional: [],
+      city: [],
+      region: [],
+      postalCode: [],
+      country: [],
+      deliveryInstructions: []
+    }
+
+    // ensure Vuelidate state object is initialized
+    if ($v && $v.value[model]) {
+      // iterate over Vuelidate object properties
+      Object.keys($v.value[model])
+        // only look at validation properties
+        .filter(prop => prop.charAt(0) !== '$')
+        .forEach(prop => {
+          // create array for each validation property
+          obj[prop] = []
+          // iterate over validation property params
+          Object.keys($v.value[model][prop])
+            .forEach(param => {
+              // add specified validation functions to array
+              switch (param) {
+                case 'required': obj[prop].push(() => vuetifyRules.requiredRule(model, prop)); break
+                case 'minLength': obj[prop].push(() => vuetifyRules.minLengthRule(model, prop)); break
+                case 'maxLength': obj[prop].push(() => vuetifyRules.maxLengthRule(model, prop)); break
+                case 'isCanada': obj[prop].push(() => vuetifyRules.isCanadaRule(model, prop)); break
+                case 'isBC': obj[prop].push(() => vuetifyRules.isBCRule(model, prop)); break
+                // FUTURE: add extra validation functions here
+                default: break
+              }
+            })
+        })
+    }
+
+    // sample return object
+    // street: [
+    //   () => this.requiredRule('addressLocal', 'street'),
+    //   () => this.minLengthRule('addressLocal', 'street'),
+    //   () => this.maxLengthRule('addressLocal', 'street')
+    // ],
+    // ...
+
+    return obj
+  }
+
+  /**
+   * The Vuetify rules object. Used to display any validation errors/styling.
+   * NB: As a getter, this is initialized between created() and mounted().
+   * @returns the Vuetify validation rules object
+   */
+  const rules = computed((): { [attr: string]: Array<Function> } => {
+    return createVuetifyRulesObject('addressLocal')
+  })
+
+  /** Array of validation rules used by input elements to prevent extra whitespace. */
+  const spaceRules = [
+    (v: string) => !/^\s/g.test(v) || 'Invalid spaces', // leading spaces
+    (v: string) => !/\s$/g.test(v) || 'Invalid spaces', // trailing spaces
+    (v: string) => !/\s\s/g.test(v) || 'Invalid word spacing' // multiple inline spaces
+  ]
+  return {
+    $v,
+    rules,
+    spaceRules
+  }
+}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@bcrs-shared-components/base-address",
-  "version": "2.0.11",
+  "version": "3.0.0",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@bcrs-shared-components/mixins": "^1.1.29",
+    "@bcrs-shared-components/enums": "^2.0.0",
+    "@bcrs-shared-components/interfaces": "^2.0.0",
+    "@bcrs-shared-components/mixins": "^2.0.0",
+    "@vuelidate/core": "^2.0.3",
     "lodash.uniqueid": "^4.0.1",
     "vue": "^2.7.14",
     "vuelidate": "0.6.2"
@@ -14,5 +17,5 @@
     "vue-property-decorator": "^9.1.2",
     "vuelidate-property-decorators": "1.0.28"
   },
-  "gitHead": "8dc1f0a920dcccabd46b1cfe57eb733131a4f6b7"
+  "gitHead": "79d7f9c9872f9eb873383c49c9d52ea94f731f90"
 }

package/resources/default-schema.ts

@@ -0,0 +1,42 @@
+import { AddressValidationRules } from '@bcrs-shared-components/enums'
+import { SchemaIF } from '@bcrs-shared-components/interfaces'
+import { baseRules, spaceRules } from '../factories/validation-factory'
+
+/* example of what to pass in for the schema */
+export const DefaultSchema: SchemaIF = {
+  street: [
+    baseRules[AddressValidationRules.REQUIRED],
+    baseRules[AddressValidationRules.MAX_LENGTH](50),
+    ...spaceRules
+  ],
+  streetAdditional: [
+    baseRules[AddressValidationRules.MAX_LENGTH](50),
+    ...spaceRules
+  ],
+  city: [
+    baseRules[AddressValidationRules.REQUIRED],
+    baseRules[AddressValidationRules.MAX_LENGTH](40),
+    ...spaceRules
+  ],
+  country: [
+    baseRules[AddressValidationRules.REQUIRED],
+    ...spaceRules
+  ],
+  region: [
+    baseRules[AddressValidationRules.REQUIRED],
+    ...spaceRules
+  ],
+  /* NOTE: Canada/US postal code and zip code regex rules
+   * are added automatically as extra rules based on country
+   * inside the address components
+   */
+  postalCode: [
+    baseRules[AddressValidationRules.REQUIRED],
+    baseRules[AddressValidationRules.MAX_LENGTH](15),
+    ...spaceRules
+  ],
+  deliveryInstructions: [
+    baseRules[AddressValidationRules.MAX_LENGTH](80),
+    ...spaceRules
+  ]
+}

package/resources/index.ts

@@ -0,0 +1 @@
+export { DefaultSchema } from './default-schema'