Componente Trascina Elemento

Componente per il caricamento di file basato sul Design System di Designers Italia, variante “Lista file” con rappresentazione statica degli stati.

Descrizione

Il componente Upload è un organismo che permette la rappresentazione dell’interfaccia di caricamento file con una struttura semantica ul/li seguendo esattamente le specifiche di Designers Italia. Il componente mostra diversi stati dei file (successo, caricamento, errore) in modo puramente visuale.

Quando Usarlo

Utilizza questo componente quando è necessario mostrare l’interfaccia di caricamento file, come:

• Form di registrazione o profili utente per foto del profilo
• Richieste di servizi online che prevedono allegati
• Piattaforme di condivisione contenuti
• Form di supporto tecnico con screenshot
• Qualsiasi contesto che richiede raccolta di documenti

Caratteristiche Principali

Struttura HTML

• Lista semantica: Utilizza <ul class="upload-file-list"> e <li class="upload-file">
• Accessibilità: Testo nascosto con visually-hidden per screen reader
• Stati visivi: Classi per success, uploading, error
• Icone SVG: Supporto per sprite SVG

Stati Supportati (tramite componente File)

• loading: File in caricamento con progress bar e pulsante cancella
• loading-error: Errore durante caricamento con icona errore e messaggio
• loading-completed: Caricamento completato con icona check
• download: File disponibile con pulsanti scarica ed elimina

Componente File

Il componente Upload utilizza il componente File separato (@file) per gestire la rappresentazione di ogni singolo file. Consulta la documentazione del componente File per maggiori dettagli sui parametri e comportamenti specifici.

Comportamento

Il componente è puramente rappresentativo e non include logica JavaScript. Mostra stati statici definiti nella configurazione. La lista dei file utilizza il componente separato @file per ogni elemento.

Struttura Lista File

La lista dei file utilizza il componente @file:

<ul class="rtds-upload__file-list">
  
</ul>

Ogni file viene renderizzato tramite il componente File che supporta i seguenti stati:

• loading: File in caricamento
• loading-error: Errore durante caricamento
• loading-completed: Caricamento completato
• download: File disponibile per download

Accessibilità

Il componente rispetta le linee guida WCAG 2.1:

• Navigazione da tastiera: Tutti gli elementi sono accessibili
• Screen reader: Span visually-hidden per contesto
• Semantica: Lista HTML semantica
• Stati ARIA: Attributi appropriati per progress bar
• Focus management: Focus chiaramente visibile

Configurazioni - Sviluppo in Nunjucks

Parametri Principali

label (string)

• Descrizione: Testo del pulsante di caricamento
• Default: “Carica file”
• Esempio: label: "Carica documenti"

multiple (boolean)

• Descrizione: Permette caricamento multiplo
• Default: true
• Esempio: multiple: false

accept (string)

• Descrizione: Tipi di file accettati
• Default: "image/*,.pdf,.doc,.docx"
• Esempi:
  • Solo immagini: "image/*"
  • Solo PDF: ".pdf"
  • Documenti: ".pdf,.doc,.docx,.txt"

helpText (string)

• Descrizione: Testo di aiuto sotto il pulsante
• Default: Informazioni sui formati supportati
• Esempio: helpText: "Dimensione massima: 5MB per file"

maxFileSize (string)

• Descrizione: Dimensione massima per file (solo informativo)
• Default: "10MB"
• Esempi: "5MB", "2GB", "500KB"

files (array)

• Descrizione: Lista di file da mostrare (utilizza componente File)
• Struttura:

  files:
    - name: "documento.pdf"
      size: "1.2MB"
      status: "loading-completed" # loading, loading-error, loading-completed, download
      progress: 100 # obbligatorio per stati loading
      errorMessage: "Messaggio di errore" # solo per loading-error

Varianti Disponibili

1. Default

context:
  label: 'Carica documenti'

• Componente base senza file mostrati

2. Con File in Diversi Stati

context:
  files:
    - name: 'documento-caricamento.pdf'
      size: '2.1MB'
      status: 'loading'
      progress: 65
    - name: 'file-completato.jpg'
      size: '850KB'
      status: 'loading-completed'
      progress: 100
    - name: 'file-errore.pdf'
      size: '15MB'
      status: 'loading-error'
      progress: 30
      errorMessage: 'File troppo grande. Max 10MB'
    - name: 'documento-download.docx'
      size: '2.1MB'
      status: 'download'

• Mostra tutti gli stati del componente File

Stili CSS

Classi Principali

• .rtds-upload: Container principale
• .rtds-upload__button-area: Area pulsante di caricamento
• .rtds-upload__button: Pulsante di caricamento
• .rtds-upload__file-list: Lista file (ul)

Le classi per i singoli file sono gestite dal componente File:

• .rtds-upload__file: Singolo file (li)
• .rtds-upload__file.loading: File in caricamento
• .rtds-upload__file.loading-error: File con errore
• .rtds-upload__file.loading-completed: File completato
• .rtds-upload__file.download: File per download

Stati Visuali

.upload-file.success {
  /* Verde per successo */
}

.upload-file.uploading {
  /* Blu per caricamento + progress bar */
}

.upload-file.error {
  /* Rosso per errore */
}

Responsive

Il componente è completamente responsive:

• Desktop: Layout orizzontale con icona, testo e pulsante
• Mobile: Layout verticale compatto

Esempi di Utilizzo

Form Semplice

### Con File Mostrati

Note di Sviluppo

Dipendenze

• Nunjucks: Per il templating
• CSS: Framework Tailwind con prefisso rtds-
• SVG Sprites: Icone tramite sprite system

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Limiti Attuali

• Solo rappresentazione statica: Nessuna logica JavaScript
• Icone fisse: Usa sempre icona generica “file”
• SVG Sprites: Richiede sprite system configurato

Best Practices

UX

1. Stati chiari: Usa colori e icone distintive per ogni stato
2. Messaggi specifici: Errori descrittivi e comprensibili
3. Accessibilità: Sempre testo nascosto per screen reader
4. Consistenza: Mantieni lo stesso pattern per tutti gli stati

Accessibilità

1. Testo nascosto: Usa visually-hidden per contesto
2. Semantica: Lista HTML per struttura logica
3. Focus: Pulsanti accessibili da tastiera
4. ARIA: Attributi appropriati per progress bar

Contenuto

1. Nomi file: Mantieni nomi descrittivi ma non troppo lunghi
2. Dimensioni: Mostra sempre la dimensione del file
3. Stati: Usa terminologia coerente (completato, caricamento, errore)
4. Messaggi: Errori specifici e azionabili

Troubleshooting

Problemi Comuni

Icone non mostrate

• Verifica path sprite SVG
• Controlla presenza file sprite
• Assicurati che ID SVG corrispondano

Stili non applicati

• Verifica inclusione CSS del componente
• Controlla prefisso classi rtds-
• Assicurati che Tailwind sia configurato

Layout rotto su mobile

• Controlla media queries responsive
• Verifica classi Flexbox
• Testa su diversi viewport

Integrazione

Per integrare funzionalità JavaScript:

1. Aggiungi event listeners ai pulsanti
2. Gestisci upload tramite fetch/XMLHttpRequest
3. Aggiorna DOM dinamicamente per stati
4. Mantieni accessibilità durante aggiornamenti

La struttura HTML è pronta per essere estesa con JavaScript mantenendo compatibilità con Designers Italia.