# useUSAddress

[← Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)

Composable that orchestrates a full US address form experience for Kendo Vue inputs.

`useUSAddress` composes:

- `useFieldsetValidationKit` for delayed validation (`submitted || touched`)
- `useZipTextBox` for dynamic ZIP/ZIP+4 formatting and validity
- internal field/state handlers for address lines, city, and state

It returns field bindings, delayed validity refs, validation/reset actions, and a normalized payload.

## Prerequisites

- Vue 3 Composition API
- Kendo Vue form inputs (`TextBox`, `DropDownList`)

## Quick Start

```ts
import { ref } from "vue";
import { useUSAddress } from "@featherk/composables/address";

const fieldsetRef = ref<HTMLFieldSetElement | null>(null);

const address = useUSAddress({
  fieldsetRef,
  addressId: "shipping-address",
  // required: true,  // optional defaults to true
});

async function onSubmit() {
  const result = await address.validateForSubmit();

  if (!result.isValid) {
    return;
  }

  // Normalized payload safe for transport
  console.log(result.payload);
}

function onReset() {
  address.reset();
}
```

## Payload

`validateForSubmit()` returns a normalized payload when valid:

```ts
export interface USAddressSubmitPayload {
  address1: string;
  address2: string;
  city: string;
  state: string; // upper-cased
  zip: string;   // digits only
}
```

Normalization rules:

- trims whitespace for `address1`, `address2`, and `city`
- upper-cases `state`
- strips non-digits from `zip`

## Returned API (high level)

State and bindings:

- `formData`
- `zipDisplay`
- `zipWrapperClass`
- `stateOptions`
- `stateDefaultItem`

Validation:

- `addressValidate`
- `address1Valid`, `cityValid`, `stateValid`, `zipValid`, `addressValid`
- `optionalFeedbackActive`, `optionalPartialInvalid`
- `optionalMissingRequiredFields`, `optionalZipInvalid`
- `touched`

Handlers:

- `onAddress1Input`, `onAddress2Input`, `onCityInput`, `onStateChange`, `onZipInput`
- `onFieldsetFocusout`

Actions:

- `validateForSubmit()`
- `reset()`

## Behavior Notes

- Delayed validation is inactive until submit or fieldset touch.
- Invalid submit focuses the first invalid Kendo control in the fieldset.
- Reset clears submit/touch state and field values.
- ZIP behavior remains delegated to `useZipTextBox`.

## Required Option

`useUSAddress` accepts an optional `required` option (`boolean` or ref/getter,
default `true`).

- `required: true` uses standard delayed validation behavior.
- `required: false` keeps required validation visuals suppressed and invalid-focus behavior disabled.

When `required` is `false`, `validateForSubmit()` behaves as follows:

- returns valid when address data is empty
- returns valid when address data is fully valid
- returns invalid for partial/invalid address data

Optional feedback semantics are exposed separately from required validation:

- `optionalPartialInvalid`: optional mode has some address input, but the address
  is not fully valid.
- `optionalFeedbackActive`: optional partial-invalid state is currently eligible
  for UX messaging (after the fieldset is blurred following the latest address
  edit, or after a failed submit attempt). This avoids showing partial-address
  feedback immediately while the user is still editing inside the fieldset.
- `optionalMissingRequiredFields`: optional mode is missing Address 1, City,
  and/or State while partial input exists.
- `optionalZipInvalid`: optional mode has address input and ZIP is not exactly
  5 or 9 digits (including empty ZIP).

Address 2 is included when detecting whether optional address input exists, but
it is excluded from the completeness requirement. Entering only Address 2 is
therefore treated as a partial optional address after fieldset blur or failed
submit.

If required toggles from `false` to `true`, validation remains dormant until the
next submit or fieldset focusout.