@authvia/address-create

v0.2.0

Published

a month ago

Authvia Address Form Web Component - Address form built with Vue 3 and Vuetify 3

Downloads

142

Authvia Address Form Web Component

A modern, accessible address form web component built with Vue 3, TypeScript, and Vuetify 3. Features Google Places autocomplete, form validation, and flexible styling options.

Features

🏠 Google Places Autocomplete - Intelligent address suggestions
📱 Responsive Design - Works on all device sizes
🎨 Customizable Styling - Vuetify theming and custom CSS variables
✅ Form Validation - Real-time validation with error handling
🔧 Flexible Configuration - Multiple props for customization
🌐 Internationalization Ready - Built-in translation support
🚀 Web Component & Vue Module - Use as web component or Vue plugin
🔒 Security Focused - Input sanitization and error handling

Installation

npm install authvia-address-form

Usage

Web Component Usage (Standalone Build)

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Address Form Demo</title>

    <!-- Vue runtime must be provided globally -->
    <script src="https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script>

    <!-- Vuetify CSS + MDI fonts (required, not bundled) -->
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/[email protected]/dist/vuetify.min.css"
      data-vuetify
    />
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@mdi/[email protected]/css/materialdesignicons.min.css"
      data-mdi
    />
  </head>
  <body>
    <!-- Basic usage -->
    <authvia-address-form
      data-azp="your-client-id"
      data-btn-text="Save Address"
      data-google-maps-api-key="YOUR_GOOGLE_MAPS_API_KEY"
    ></authvia-address-form>

    <!-- With prefilled data -->
    <authvia-address-form
      data-azp="your-client-id"
      data-street-address="123 Main St"
      data-city="New York"
      data-state="NY"
      data-country="United States"
      data-postal-code="10001"
      data-btn-text="Update Address"
      data-prepend-icon="true"
      data-google-maps-api-key="YOUR_GOOGLE_MAPS_API_KEY"
    ></authvia-address-form>

    <!-- Read-only / disabled form -->
    <authvia-address-form
      data-azp="your-client-id"
      data-disable-form="true"
      data-street-address="456 Market St"
      data-city="San Francisco"
      data-state="CA"
      data-country="United States"
      data-postal-code="94105"
      data-btn-text="Submit Disabled"
      data-google-maps-api-key="YOUR_GOOGLE_MAPS_API_KEY"
    ></authvia-address-form>

    <!-- Load the web component (use either .js or .umd.cjs) -->
    <script src="https://cdn-development.authvia-nonprod.com/web-components/authvia-address-create/authvia-address-create.js"></script>
    <!-- Or UMD version: https://cdn-development.authvia-nonprod.com/web-components/authvia-address-create/authvia-address-create.umd.cjs -->
  </body>
</html>

Vue Module Usage

Important: The Vue module does not create a Vuetify instance. Your app must provide Vuetify and the MDI font CSS.

Basic Vuetify Setup

import { createApp } from 'vue'
import { createVuetify } from 'vuetify'
import * as components from 'vuetify/components'
import * as directives from 'vuetify/directives'
import 'vuetify/styles'
import '@mdi/font/css/materialdesignicons.css'

const vuetify = createVuetify({
  components,
  directives,
  theme: {
    defaultTheme: 'light'
  }
})

const app = createApp(App)
app.use(vuetify)
app.mount('#app')

Use the component (with Google Maps API key)

Use normalized prop names (no data prefix). In templates you can use kebab-case (e.g. btn-text) or camelCase (btnText).

<template>
  <div>
    <AuthviaAddressForm
      :azp="clientId"
      :btn-text="btnText"
      :street-address="address.street"
      :city="address.city"
      :state="address.state"
      :country="address.country"
      :postal-code="address.postalCode"
      :google-maps-api-key="googleMapsApiKey"
      :prepend-icon="true"
      @submit="handleSubmit"
      @success="handleSuccess"
      @error="handleError"
      @field-input="handleFieldInput"
      @field-blur="handleFieldBlur"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { AuthviaAddressForm } from 'authvia-address-form'
import type { AddressFormData } from 'authvia-address-form'

const clientId = ref('your-client-id')
const btnText = ref('Save Address')

const address = ref({
  street: '123 Main St',
  city: 'New York',
  state: 'NY',
  country: 'United States',
  postalCode: '10001'
})

const googleMapsApiKey = ref(import.meta.env.VITE_APP_GOOGLE_MAPS_API_KEY || '')

const handleSubmit = (data: AddressFormData) => {
  console.log('Form submitted:', data)
}

const handleSuccess = (data: any) => {
  console.log('Success:', data)
}

const handleError = (error: any) => {
  console.error('Error:', error)
}

const handleFieldInput = (field: keyof AddressFormData, value: string) => {
  console.log(`Field ${field} changed to:`, value)
}

const handleFieldBlur = (field: keyof AddressFormData) => {
  console.log(`Field ${field} lost focus`)
}
</script>

Vue Plugin Usage

Important: Your consuming application must configure Vuetify first (see Vue Module Usage above), then use the plugin:

import { createApp } from 'vue'
import { createVuetify } from 'vuetify'
import '@mdi/font/css/materialdesignicons.css'
import 'vuetify/styles'
// ... configure Vuetify as above ...
import AuthviaAddressForm from 'authvia-address-form'
import App from './App.vue'

const app = createApp(App)
app.use(vuetify) // Your Vuetify instance
app.use(AuthviaAddressForm) // Then use the plugin
app.mount('#app')

Note:

The plugin only registers the component.
Vuetify (including icons) is fully controlled by your app; we recommend using the MDI font CSS as shown above.

Props

Prop naming

Vue module: Use normalized names (no data prefix). In the template use kebab-case (e.g. :azp, :btn-text, :prepend-icon). In script/TypeScript the type AuthviaAddressFormProps uses camelCase (azp, btnText, prependIcon).
Web component: Use data-* attributes on the element (e.g. data-azp, data-btn-text, data-prepend-icon). The component maps these into the same normalized shape internally.

Vue module (normalized names)

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | azp | string | Yes | — | Client identifier | | token | string | No | — | Authentication token for API calls | | googleMapsApiKey | string | No | — | Google Maps API key for Places autocomplete. Falls back to VITE_APP_GOOGLE_MAPS_API_KEY in Vue apps. | | btnText | string | No | 'Submit Address' | Submit button label | | noButton | boolean | No | false | Hide submit button | | prependIcon | boolean | No | true | Show prepend icons in inputs | | streetAddress, city, state, country, postalCode | string | No | — | Prefill address fields | | union | string | No | — | Union identifier for API address lookup | | compactMode | boolean | No | false | Use compact spacing between fields | | parentForm | boolean | No | false | Component is part of a larger form | | autoSubmit | boolean | No | false | Auto-submit when form becomes valid (hides button) | | disableForm | boolean | No | false | Disable all fields and submit button (read-only) | | inputSpacing | string | No | — | Spacing between inputs | | vuetifyOverrides | string | No | — | Optional CSS string to override Vuetify styles. Injected as a <style> on the form root. | | color | string | No | '#4CAF50' | Primary theme color HEX value. Sets --avwc-color on the form root. | | variant | string | No | 'outlined' | Vuetify variant: "solo", "outlined", "filled", "plain", "underlined", etc. | | borderRadius | string | No | '1rem' | Border radius for inputs and buttons. Sets --avwc-border-radius on the form root. |

Web component (data-* attributes)

Use these attributes on the <authvia-address-form> element. They map to the same props as above.

| Attribute | Type | Description | |-----------|------|-------------| | data-azp | string | Client identifier (required) | | data-token | string | Authentication token | | data-google-maps-api-key | string | Google Maps API key for Places autocomplete | | data-btn-text | string | Submit button label | | data-no-button | "true" | Hide submit button | | data-prepend-icon | "true" | Show prepend icons in inputs | | data-street-address, data-city, data-state, data-country, data-postal-code | string | Prefill address fields | | data-union | string | Union identifier for API address lookup | | data-compact-mode | "true" | Compact spacing | | data-parent-form | "true" | Part of larger form | | data-auto-submit | "true" | Auto-submit when valid | | data-disable-form | "true" | Disable form (read-only) | | data-input-spacing | string | Spacing between inputs | | data-vuetify-overrides | string | Raw CSS string to override Vuetify styles (injected as <style> on the form root). | | data-color | string | Primary theme color (e.g. '#1976d2'). Sets --avwc-color. | | data-variant | string | Vuetify variant: "outlined", "filled", "underlined", etc. | | data-border-radius | string | Border radius for inputs and buttons (e.g. '1rem'). Sets --avwc-border-radius. |

Customization (CSS Variables)

Theming uses only two CSS variables (aligned with payment-method-credit-card). They are set from the color and borderRadius props on the internal form root (the published Vue component applies them there directly; the dev wrapper forwards the same props). You can also set them on a parent element or :root when using the Vue module.

| Variable | Description | |----------|-------------| | --avwc-color | Primary color (buttons, focus border, title). Set via color prop or CSS. | | --avwc-border-radius | Border radius for inputs and buttons. Set via borderRadius prop or CSS. |

All other styling (text color, font, button text, etc.) uses fixed fallbacks. For further overrides, use the vuetifyOverrides prop (raw CSS string).

Events

| Event | Detail | Description | |-------|--------|-------------| | submit | AddressFormData | Form submitted with data | | success | { data, azp } | Form submission successful | | error | { error, azp } | Form submission failed | | field-input | { field, value } | Field value changed | | field-blur | { field } | Field lost focus |

Types

Component props use the normalized interface AuthviaAddressFormProps (see Props); the web component maps data-* attributes into this same shape.

interface AddressFormData {
  streetAddress: string
  city: string
  state: string
  country: string
  postalCode: string
}

Configuration

Environment Variables

# API Configuration
VITE_APP_API_BASE_URL=https://api-dev.authvia.com
VITE_APP_API_VERSION=v3

# Google Maps (optional fallback if prop not provided)
VITE_APP_GOOGLE_MAPS_API_KEY=your-google-maps-api-key

# Development / diagnostics
VITE_APP_ENABLE_LOGGING=true
VITE_APP_ENABLE_DEBUG=true
VITE_APP_ENABLE_ANALYTICS=false
VITE_APP_ENABLE_ERROR_REPORTING=false
VITE_APP_ENABLE_PERFORMANCE_MONITORING=false
VITE_APP_ENABLE_CSP=true
VITE_APP_ENABLE_HSTS=false
VITE_APP_BUILD_TARGET=development
VITE_APP_SOURCE_MAPS=true

Google Maps API Key

To enable address autocomplete, you need a Google Maps API key with the Places API enabled:

Go to Google Cloud Console
Create a new project or select existing one
Enable the Places API
Create credentials (API key)
Set the API key in your environment variables

Development

Prerequisites

Node.js 18+
npm 9+

Setup

# Install dependencies
npm install

# Start development server
npm run dev

# Build web component
npm run build:wc

# Build Vue module
npm run build

# Type checking
npm run type-check

# Linting
npm run lint

Project Structure

src/
├── components/
│   └── AuthviaAddressForm.vue      # Main component
├── composables/
│   └── useAddressService.ts        # Address service composable
├── services/
│   └── GoogleMapsService.ts        # Google Maps integration
├── utils/
│   ├── config.ts                   # Configuration utilities
│   ├── errors.ts                   # Error handling
│   └── spacing.ts                  # Spacing utilities
├── types/
│   └── index.ts                    # TypeScript types
├── entry/
│   ├── web-component.ts            # Web component entry
│   └── index.ts                    # Vue module entry
└── styles/
    └── variables.css               # CSS variables

Bundle & Assets

The Vue module externalizes Vue and Vuetify; your app controls Vuetify configuration and icon sets (we recommend the MDI font CSS).
The standalone web component bundles Vuetify JavaScript but expects Vuetify CSS + MDI fonts from the host page.
Component CSS is injected by JS (no separate style.css export); you don’t need to import any additional styles from this package beyond Vuetify + MDI.

Browser Support

Chrome 88+
Firefox 85+
Safari 14+
Edge 88+

License

MIT License - see LICENSE file for details.

Support

For support and questions, please contact the Authvia UI Team.