# File-Selector

Komponente des SBB Design Systems Lyne.

- Paket: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Aufbau: mehrere eigenständige Elemente
- Kategorien: Form
- Status: Gestaltungsrichtlinien vollständig

## Links

- Seite auf digital.sbb.ch: https://digital.sbb.ch/de/design-system/lyne/components/file-selector/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-file-selector--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/file-selector/overview (API: https://lyne-angular.app.sbb.ch/angular/components/file-selector/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=7491-28
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/file-selector

## Elemente

- `sbb-file-selector`: It allows to select one or more file from storage devices and display them.
- `sbb-file-selector-dropzone`: It allows to select one or more file from storage devices via button click or drag and drop, and display them.

## Übersicht

### Was macht die Komponente?
Mit dem File-Selector wählen Nutzende eine oder mehrere Dateien von ihrem Gerät aus. Die gewählten Dateien erscheinen mit Name und Grösse in einer Liste und lassen sich wieder entfernen. Es gibt zwei Varianten: Button und Dropzone. In der Dropzone lassen sich Dateien per Drag-and-drop ablegen.

### Wann soll die Komponente eingesetzt werden?
* Um Dateien wie Dokumente, Bilder oder Videos anzuhängen.
* Um Formulare zu ergänzen, die Dateianhänge erfordern.

### Regeln.
* Die Dropzone eignet sich bei mehreren oder grossen Dateien, der Button bei einzelnen Dateien und wenig Platz.
* Erlaubte Dateitypen werden eingeschränkt und für Nutzende angegeben.
* Ob mehrere Dateien möglich sind, ist klar erkennbar.
* Fehler (z.B. falscher Dateityp) werden mit einer verständlichen Fehlermeldung angezeigt.
* Die Komponente wählt nur aus. Das Hochladen und ein allfälliger Fortschritt liegen in der Anwendung.
* Mit einem eigenen Accessibility-Label unterscheiden sich Button und Dropzone für Screenreader.

## Implementation (Web Components, Englisch)

The `<sbb-file-selector>` and `<sbb-file-selector-dropzone>` are components which allows user to select
one or more files from storage devices.
These are two variants with the same functionality.
When files are selected, they appear as a list below the button/dropzone area.
For each file, the name and the size are displayed and an icon allows for deletion.
The component mimics the native `<input type="file"/>`.

```html
<sbb-file-selector></sbb-file-selector>
```

The dropzone variant is displayed as a panel on which files can more easily be dragged and dropped.
It is possible to customize the area's title via the `titleContent` property.

```html
<sbb-file-selector-dropzone></sbb-file-selector-dropzone>
```

### Slots

The `error` named slot can be used to display an error message using the `<sbb-error>` component.

```html
<sbb-file-selector>
  <sbb-error slot="error">An error occurred during file upload.</sbb-error>
</sbb-file-selector>

<sbb-file-selector-dropzone>
  <sbb-error slot="error">An error occurred during file upload.</sbb-error>
</sbb-file-selector-dropzone>
```

### States

User interaction can be disabled using the `disabled` property.

```html
<sbb-file-selector disabled></sbb-file-selector>

<sbb-file-selector-dropzone disabled></sbb-file-selector-dropzone>
```

#### Multiple and multipleMode

A single file can be selected by default; this can be changed setting the `multiple` property to `true`.

```html
<sbb-file-selector multiple></sbb-file-selector>

<sbb-file-selector-dropzone multiple></sbb-file-selector-dropzone>
```

The value of the `multipleMode` property determines whether added files should overwrite existing files (`default`) or be appended to them (`persistent`).

```html
<sbb-file-selector multiple multiple-mode="persistent"></sbb-file-selector>

<sbb-file-selector-dropzone multiple multiple-mode="persistent"></sbb-file-selector-dropzone>
```

#### Accept

The `accept` property can be used to force the user to select one or more specific file types;
in the next example, only images are allowed.

```html
<sbb-file-selector accept=".png,.jpg,.jpeg"></sbb-file-selector>

<sbb-file-selector-dropzone accept=".png,.jpg,.jpeg"></sbb-file-selector-dropzone>
```

### Style

The component has also two different sizes, `s` and `m`, which can be changed using the `size` property.

```html
<sbb-file-selector size="s"></sbb-file-selector>

<sbb-file-selector-dropzone size="m"></sbb-file-selector-dropzone>
```

#### Events

Whenever the selection changes, a `filechanged` event is fired, whose `event.files` property contains the list
of currently selected files. The list can also be retrieved using the public `files` getter.

### Accessibility

It's possible to improve the component accessibility using the `accessibilityLabel` property; this will be set
as `aria-label` of the inner native input and read together with the visible button text.
It's suggested to have a different value for each variant, e.g.:

```html
<sbb-file-selector accessibility-label="Select a file from hard disk"></sbb-file-selector>
<sbb-file-selector
  multiple
  accessibility-label="Select from hard disk - multiple selection allowed"
></sbb-file-selector>

<sbb-file-selector-dropzone
  accessibility-label="Select a file from hard disk"
></sbb-file-selector-dropzone>
<sbb-file-selector-dropzone
  multiple
  accessibility-label="Select from hard disk - multiple selection allowed"
></sbb-file-selector-dropzone>
```

## API (Web Components, Englisch)

Vollständige API-Tabellen (Attribute, Events, Slots, CSS-Eigenschaften): https://digital.sbb.ch/de/design-system/lyne/components/file-selector/api.md