Forms

FormHelperText

Componente per testo di aiuto e messaggi di errore sotto i campi form. Il messaggio di errore ha priorità sul testo di aiuto. Supporta icona errore opzionale e ID per aria-describedby.

Import

import { FormHelperText } from '@pzeta/vue-components'

Esempio Base

Props

Prop	Tipo	Default	Descrizione
`helperText`	`string \| null`	`null`	Testo di aiuto mostrato quando non c'è errore
`error`	`string \| null`	`null`	Messaggio di errore (ha priorità su `helperText`)
`componentPrefix`	`string`	`'form'`	Prefisso per le classi CSS BEM (`hs-{prefix}-helper-text`)
`showErrorIcon`	`boolean`	`false`	Mostra icona prima del messaggio di errore
`errorIcon`	`string`	config globale	Classe CSS icona di errore
`helperId`	`string \| null`	`null`	ID per l'elemento helper text (per `aria-describedby`)
`errorId`	`string \| null`	`null`	ID per l'elemento error text (per `aria-describedby`)

Slot

Slot	Scope	Descrizione
`helper`	—	Contenuto personalizzato per il testo di aiuto
`error`	—	Contenuto personalizzato per il messaggio di errore

Esempi

Helper text standard

Messaggio di errore

<template>
  <div>
    <input id="email" type="email" :class="{ 'border-red-500': emailError }" />
    <FormHelperText
      helper-text="Inserisci la tua email aziendale"
      :error="emailError ? 'Email non valida' : null"
    />
    <!-- Quando error è presente, helperText viene nascosto -->
  </div>
</template>

Con icona di errore

Con ID per accessibilità

Con slot personalizzati

<template>
  <FormHelperText :error="errore">
    <template #helper>
      <span class="flex items-center gap-1">
        <i class="pi pi-info-circle text-xs"></i>
        Testo di aiuto con icona personalizzata
      </span>
    </template>
    <template #error>
      <span class="font-semibold">Errore: {{ errore }}</span>
    </template>
  </FormHelperText>
</template>

Comportamento

Quando error è presente, viene mostrato il messaggio di errore e helperText viene nascosto
Quando error è null/undefined e helperText è presente, viene mostrato il testo di aiuto
Il messaggio di errore ha role="alert" per notificare gli screen reader automaticamente
Se entrambi sono null, il componente non renderizza nulla

Classi CSS Generate

Le classi CSS seguono la convenzione BEM con prefisso hs-{componentPrefix}:

Elemento	Classi applicate
Helper text (normale)	`hs-{prefix}-helper-text hs-{prefix}-helper-text-default`
Helper text (con errore presente)	`hs-{prefix}-helper-text hs-{prefix}-helper-text-error`
Error text	`hs-{prefix}-error-text`

Accessibilità

Il contenitore dell'errore ha role="alert" per notifica immediata agli screen reader
Le prop helperId e errorId permettono di collegare gli elementi all'input tramite aria-describedby
InputMask usa questa feature internamente per gestire l'accessibilità degli ID

TypeScript

import type { FormHelperTextProps } from '@pzeta/vue-components'

// FormHelperTextProps è definita internamente al componente
// Non è esportata come tipo dedicato dal package

const helperProps = {
  helperText: 'Testo di aiuto',
  error: null,
  showErrorIcon: false,
  componentPrefix: 'mycomponent',
}

Nota: FormHelperText è usato internamente da tutti i componenti form della libreria. Va usato direttamente solo quando si costruisce un campo form personalizzato.

FloatLabel

Wrapper che trasforma una label statica in una label fluttuante che si anima sopra l'input al focus o quando il campo ha un valore. Supporta tre varianti di posizionamento.

FormLabel

Etichetta accessibile per campi form. Supporta stato di errore, indicatore di campo obbligatorio con testo nascosto per screen reader e personalizzazione tramite slot.