Correct and idiomatic ways to use the <mds-file> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Basic File Card

The minimal form. Pass filename with a real filename (including extension) and the component auto-detects the format icon, badge color, and localized description.

<mds-file filename="relazione-annuale.pdf"></mds-file>

Handling the Download Event

The component does not fetch or download anything by itself. Listen for mdsFileDownload and trigger the actual download in the event handler. The event detail carries filename, extension, type, description, and target.

<mds-file filename="contratto-servizio.docx" id="file-card"></mds-file>

<script>
  document.getElementById('file-card').addEventListener('mdsFileDownload', (event) => {
    const { filename, extension, type } = event.detail;
    console.log(`Download avviato: ${filename} (${type})`);
    // avvia il download effettivo dal server
  });
</script>

Forcing a File Type with suffix

When the filename lacks an extension or carries a misleading one, use suffix to force a specific format from the supported set.

<!-- filename senza estensione - forza il riconoscimento come PDF -->
<mds-file filename="documento-firmato" suffix="pdf"></mds-file>

<!-- estensione sconosciuta - forzata come archivio ZIP -->
<mds-file filename="backup.bkp" suffix="zip"></mds-file>

Custom Description

Override the localized auto-generated description with a specific label relevant to the document context. Use description when the default type label (e.g. “Documento Adobe” for a PDF) is not informative enough.

<mds-file
  filename="verbale-cda-2024.pdf"
  description="Verbale approvato dal Consiglio di Amministrazione"
></mds-file>

Image Preview

Provide preview with an image URL when a meaningful visual thumbnail is available - a logo, a reduced version of an image file, or a document cover. The preview replaces the generic format icon in the left panel.

<mds-file
  filename="logo-aziendale.png"
  preview="https://cdn.example.com/thumbnails/logo-aziendale-128.png"
></mds-file>

Hiding the “Already Downloaded” Indicator

The component shows a “done” indicator once the file has been downloaded, on every later render of the same filename. Add hide-downloaded-icon to suppress it when the affordance is not appropriate for the context (e.g. a list where every file is always shown as fresh).

<mds-file filename="modulo-richiesta.xlsx" hide-downloaded-icon></mds-file>

Note: this is the only valid way to turn the indicator off. Magma 1 used show-downloaded-icon="false"; that prop no longer exists (the codemod turns it into hide-downloaded-icon).

Rendering a List of Files

Place multiple <mds-file> cards inside a container and attach a single delegated event listener when the file list is dynamic.

<div class="file-list">
  <mds-file filename="allegato-1.pdf"></mds-file>
  <mds-file filename="allegato-2.docx"></mds-file>
  <mds-file filename="allegato-3.xlsx"></mds-file>
</div>

<script>
  document.querySelector('.file-list').addEventListener('mdsFileDownload', (event) => {
    const { filename } = event.detail;
    avviaDownload(filename);
  });
</script>

Styling Customization

Style the preview panel only through the three documented --mds-file-* CSS custom properties. Use the semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working.

.archivio-documenti mds-file {
  --mds-file-preview-icon-color: rgb(var(--magma-accent-fg));
  --mds-file-preview-icon-background: rgb(var(--magma-accent-surface-subtle));
  --mds-file-preview-color: rgb(var(--magma-accent-fg));
}