# Time-Input

Komponente des SBB Design Systems Lyne.

- Paket: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Aufbau: ein Element
- Kategorien: Form
- Status: Gestaltungsrichtlinien vollständig

## Links

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

## Elemente

- `sbb-time-input`: Custom input for a time.

## Übersicht

### Was macht die Komponente?
Ein Time-Input ist ein Eingabefeld für eine Uhrzeit. Die Eingabe wird automatisch als HH:mm formatiert.

### Wann soll die Komponente eingesetzt werden?
* Wenn Nutzende eine genaue Uhrzeit eingeben sollen, z.B. für Abfahrtszeiten oder Termine.

### Regeln.
* Der Time-Input wird im [Form-Field](https://digital.sbb.ch/de/design-system/lyne/components/form-field/) verwendet.
* Eingaben wie `1`, `123` oder `12.30` werden automatisch zu `01:00`, `01:23` bzw. `12:30` formatiert. Zulässige Trennzeichen sind `.`, `:`, `,` und `-`.
* Ungültige Zeiten (z.B. 25:30) werden nicht formatiert. Die Anwendung prüft und meldet solche Eingaben.

## Implementation (Web Components, Englisch)

The `<sbb-time-input>` is an input component that displays the typed value as a formatted time (HH:mm).

```html
<sbb-time-input value="15:00"></sbb-time-input>
```

The component allows the insertion of up to 4 numbers, possibly with a separator char like `.`, `:`, `,` or `-`,
then automatically formats the value as time and displays it (see ["Format example"](#format-example)).

### In `<sbb-form-field>`

The `<sbb-time-input>` can be used within an `<sbb-form-field>`:

```html
<sbb-form-field width="collapse" size="s">
  <sbb-time-input value="13:30"></sbb-time-input>
</sbb-form-field>
```

The initial value can be set using the `value` property (string) or attribute.
To get or set the value as a `Date` object, the `valueAsDate` property can be used.
The returned date has its date always set to 01.01.1970 and only the hours and minutes
are set to the current value of the element.
e.g.: with a value of `12:34`, the `valueAsDate` will be 01.01.1970, 12:34:00 UTC.

If the value is invalid because not real (e.g. 12:61 or 25:30), the component does
not format the `value`, and `valueAsDate` will return `null`.

### Format example

See the table below for some formatting examples:

| Input | Output |
| ----- | ------ |
| 12:34 | 12:34  |
| 1     | 01:00  |
| 12    | 12:00  |
| 123   | 01:23  |
| 1234  | 12:34  |
| 1.    | 01:00  |
| 1.2   | 01:02  |
| 1.23  | 01:23  |
| 12:   | 12:00  |
| 12.3  | 12:03  |
| 12,34 | 12:34  |
| 12-34 | 12:34  |

### Events

Similar to the native `<input>` element, the `<sbb-time-input>` component
dispatches the usual `input`, `change`, `blur`, `invalid` and keyboard
and focus related events.

## API (Web Components, Englisch)

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