Datepicker

npm install @entur/datepicker

@import '@entur/datepicker/dist/styles.css';

() => {
    const [date, setDate] = React.useState(now('Europe/Oslo'));
    return (
      <DatePicker
        label="Dato"
        selectedDate={date}
        onChange={date => setDate(date)}
        locale="nb-NO"
      />
    );
  }

Kom i gang

DatePicker hjelper brukeren å velge en dato – og evt. et tidspunkt. Den bruker pakken @internationalized/date i bakgrunnen til håndtering av dato-objektet, inkludert tidssoner – dette er tilsvarende i TimePicker. DatePicker støtter også ulike locals og språk. DatePicker bygger på react-aria og støtter det meste av funksjonalitet du finner der, les mer her.

Språk og locale

Språk og locals er støttet gjennom to metoder. All automatisk tilpassing av språk skjer gjennom prop-en locale eller react-aria sin <I18nProvider />. locale støtter strenger på BCP 47-formatet, eks. nb-NO for norsk. Her finner du en liste over BCP 47-koder. Som default velges den locale-en som er satt på brukeren maskin.

Ledeteksten (label), og navigationDescription* må sende inn manuell oversettelse for. For navigationDescription vil en norsk og engelsk verdi følge med automatisk, men andre språk må legges inn selv.

*navigationDescription er en prop som forteller brukeren hvordan de kan navigere i kalenderen med tastaturet.

DatePicker tilpasset USA

() => {
    const [date, setDate] = React.useState(now('Europe/Oslo'));
    return (
      <DatePicker
        label="Date"
        selectedDate={date}
        onChange={date => setDate(date)}
        locale="en-US"
      />
    );
  }

Tidssoner

TimePicker støtter tidssonehåndtering for å sikre lik opplevelse på tvers av tidssoner. Dette håndteres ved @internationalized/date sitt ZonedDateTime-objekt. Under er et eksempel på hvordan du lager state for nåværende dato og tidspunkt i norsk tidssone, og for et spesifikt tidspunkt i Los Angeles sin tidssone:

Les mer om hvordan opprette og bruke tidssonefunksjonalitet her.

// nåværende tidspunkt i norsk tidssone
const [date, setDate] = React.useState(now('Europe/Oslo'));
// spesifikt tidspunkt i Los Angeles sin tidssone
const [date2, setDate2] = React.useState(parseZonedDateTime('2022-11-07T00:45[America/Los_Angeles]'));

Datovalidering

Hvis du ønsker å begrense tilgjengelige datoer for brukeren, samt gi en tilbakemelding når en dato utenfor dette intervallet er valgt, kan du benytte minDate- og maxDate-props-ene eller isDateUnavailable()-valideringsfunksjonen. minDate og maxDate tar inn et CalendarDate-objekt. isDateUnavailable() skal ta inn en DateValue og returnerer en boolean for om datoen er gyldig.

Validering med minDate og maxDate

Følgende eksempel godtar datoer fra og med i dag til og med en måned frem:

() => {
    const [date, setDate] = React.useState(
      today('Europe/Oslo').add({ months: 2 }),
    );
    return (
      <DatePicker
        label="Velg dato"
        selectedDate={date}
        onChange={setDate}
        locale="nb-NO"
        minDate={today('Europe/Oslo')}
        maxDate={today('Europe/Oslo').add({ months: 1 })}
        validationFeedback="Valgt dato er for langt frem i tid"
      />
    );
  }

Validering med isDateUnavailable

Følgende eksempel godtar datoer som ikke er en helg.

() => {
    const [date, setDate] = React.useState(now('Europe/Oslo'));
    return (
      <DatePicker
        label="Velg dato"
        selectedDate={date}
        onChange={setDate}
        locale="nb-NO"
        isDateUnavailable={date => isWeekend(date, 'nb-NO')}
        validationFeedback="Valgt dato kan ikke være en helgedag"
      />
    );
  }

Bruke JS Date i stedet for @internationalized/date

Hvis du ikke har mulighet til å bruke @internationalized/date, kan du bruke konverteringsfunksjonene: nativeDateToDateValue og timeOrDateValueToNativeDate. Disse konverterer mellom @internationalized/date sine tre dato-typer: ZonedDateTime, CalendarDateTime og CalendarDate (DateValue er en samling av disse tre typene) og Javascript sin Date. Se API under, nærmere beskrivelse finnes i JSDocs for funksjonene:

nativeDateToDateValue: (date: Date | null, noTimeOnlyDate?: boolean, timeZone?: string | undefined, offset?: number | undefined) => CalendarDateTime | ZonedDateTime | CalendarDate | null;
timeOrDateValueToNativeDate: (value: TimeValue | DateValue | null, timeZoneForCalendarDateTime?: string | undefined) => Date | null;

Eksempel på bruk av JS-date med DatePicker

Bruk sammen med TimePicker

Du kan velge et tidspunkt sammen med datoen på to ulike måter, enten inline med granularity="minute" eller granularity="second"- prop-en (avhengig om du vil vise sekund eller ikke) eller ved å bruke en TimePicker i kombinasjon med DatePicker-en.

Inline

() => {
    const [date, setDate] = React.useState(now('Europe/Oslo'));
    return (
      <DatePicker
        label="Velg dato og tid"
        selectedDate={date}
        onChange={setDate}
        locale="nb-NO"
        granularity="minute"
      />
    );
  }

Kombinasjon med TimePicker

I løsninger ut mot vanlige sluttbrukere er en separat dato- og tid-velger foretrukket.

() => {
    const [dateTime, setDateTime] = React.useState(null);
    return (
      <div style={{ display: 'flex', gap: '1rem' }}>
        <DatePicker
          label="Dato"
          selectedDate={dateTime}
          onChange={setDateTime}
          locale="nb-NO"
        />
        <TimePicker
          label="Tid"
          selectedTime={dateTime}
          onChange={setDateTime}
          locale="nb-NO"
        />
      </div>
    );
  }

Bruk på mobile enheter

DatePicker fungerer også på mobile enheter. For å gjøre valg enklere for brukere med berøringskjermer benyttes en modal i stedet for en popover når skjermen er smalere enn 1000px. På denne måten vil alltid hele datovelgeren vises når man åpner den. Dette er mulig å skru av ved å bruke prop-en disableModal.

Ønsker man en OS-spesifikk opplevelse av DatePicker-en, kan man benytte seg av NativeDatePicker. Denne har noe styling for å gi den et Entur-preg, men vil bruke OS-et sin styling og interaksjonsmetode når man interagerer med den.

()=> {
    return (
      <NativeDatePicker
        label="Fødselsdato"
        style={{ width: '15rem' }}
        value="1997-07-10"
      />
    );
  }

Kun kalender

Hvis du ønsker å kun vise en inline kalender til brukeren kan du benytte <Calendar />-komponenten. Denne fungerer med samme type datoobjekter som <DatePicker /> og støtter mange av de samme props-ene.

Styling av datoer i kalenderen

Både DatePicker og Calendar har støtte for prop-en classNameForDate. classNameForDate skal være en funksjon som tar inn en dato og returnerer en streng med klassenavnet som skal legges til for dato-ruten.

Hvis stylingen som legges til er meningsbærende bør du også bruke ariaLabelForDate til å beskrive stylingens mening for skjermlesere o.l.

Vise ukenummer

Hvis du trenger å vise ukenummer i kalenderen kan du benytte prop-en showWeekNumbers. Du kan endre overskriften til ukenummerkolonnen ved å bruke prop-en weekNumberHeading.

Kun inputfelt

Hvis du ønsker å kun vise et inputfelt uten mulighet for en kalender-popover kan du benytte <DateField />-komponenten. Denne fungerer med samme type datoobjekter som <DatePicker /> og støtter mange av de samme props-ene.

Spesielle tilfeller

forcedReturnType

Prop-en forcedReturnType lar deg tvinge gjennom et dato/tid-objekt du vil ha ut fra datepicker sin onChange. Som standard sendes samme dato/tid-objekttype ut fra DatePicker som det det får inn, dvs. selectedDate: T gir onChange : (selectedDate: T) => void. Hvis selectedDate == null vil DatePicker som standard gi onChange : (selectedDate: ZonedDateTime) => void. Ønsker du å overskrive denne oppførselen kan du bruke forcedReturnType. Typen du skriver inn her vil alltid bli sendt med i onChange, dvs. forcedReturnType="T" onChange : (selectedDate: T) => void. forcedReturnType støtter i dag CalendarDate, CalendarDateTime og ZonedDateTime.

'Invalid granularity for …' feilmelding

Hvis du sender inn et tid/datoobjekt som har færre felter enn det dato/tidvelgeren din viser, eksempelvis et CalendarDate-objekt (uten tidspunkt) til en TimePicker, vil du få feilmeldingen: 'Invalid granularity for …'. Dette kan for eksempel skje hvis du bruker forcedReturnType for å tvinge ut et annet dato-objekt med færre felter.

Retningslinjer

Universell utforming

DatePicker bruker react-aria i bakgrunnen.Denne pakken sørger for gjennomgående støtte for universell utforming. Hvert datosegment er tilgjengelig med tastaturet og alle interagerbare elementer, både i inputfeltet og i kalenderen, har aria-beskrivelser.

Hvis du endrer locale (dvs. språk) til noe annet enn norsk og engelsk må du sende inn verdier på riktig språk til navigationDescription-prop-en.

Komponenter

DatePicker

import { DatePicker } from '@entur/datepicker';

Denne komponenten har ingen props

DateField

import { DateField } from '@entur/datepicker';

Denne komponenten har ingen props

Calendar

import { Calendar } from '@entur/datepicker';

Denne komponenten har ingen props

NativeDatePicker

import { NativeDatePicker } from '@entur/datepicker';

Denne komponenten har ingen props