LilyDesignSystem.Blazor.TimeZonePicker 0.1.0

TimeZonePicker (Blazor helper)

A reusable Blazor headless time zone picker: an icon button that opens a WAI-ARIA APG listbox of time zones, each shown as its UTC offset and its full name (UTC+05:30 – India Standard Time), ordered by offset from west to east. On every change it sets data-time-zone="{IANA id}" on a target element (default document.documentElement), optionally persisting the choice to localStorage. Ships no CSS.

The value is an IANA zone id (Asia/Kolkata), which is what Intl.DateTimeFormat({ timeZone }) and every date library take. The offsets and names are not a table in this package: they are computed with Intl for the locale you pass, on the date you pass (default now), so the same zone reads UTC-05:00 – Eastern Standard Time in January and UTC-04:00 – Eastern Daylight Time in July, and Central European Standard Time becomes heure normale d’Europe centrale for fr.

// What the app does with the choice:
new Intl.DateTimeFormat(locale, { timeZone: document.documentElement.dataset.timeZone }).format(date);

Usage

@using LilyDesignSystem.Blazor.Helpers

<TimeZonePicker Label="Time zone" Locale="en-GB" @bind-Value="zone" StorageKey="lily-time-zone" />

@code {
    private string zone = "";
}

Blazor idioms: install LilyDesignSystem.Blazor.TimeZonePicker; @bind-Value and @bind-Open bind the zone and the popup, OnChange fires once per applied change, CssClass adds a class to the root, unmatched attributes land on the root, and ChildContent is a RenderFragment<TimeZonePickerContext> replacing the icon (context.InfoFor(context.Value)). The pure rules are public as the static class TimeZones (Ordered, Info, OffsetMinutes, FormatOffset, MatchZone, DefaultZones).

Deviation from the other catalogs: .NET has no API for a zone's full name in an arbitrary locale (Intl has one; TimeZoneInfo does not). Offsets and order are exact (TimeZoneInfo), and the name is, in order: the Names parameter (a dictionary of IANA id to (Standard, Daylight) name, in the reader's language), else the platform's own standard or daylight name. For a localized name use the Unicode CLDR names that LilyDesignSystem.Blazor.LocaleTranslations ships (below). The reader's own zone is read from the browser (Intl.DateTimeFormat().resolvedOptions().timeZone), not from the server's TimeZoneInfo.Local.

Props

The pure rules are public in the static class TimeZones: Ordered, Info, OffsetMinutes, FormatOffset, ZoneName, MatchZone, DefaultLabel, DefaultZones.

Zone names from Unicode CLDR

LilyDesignSystem.Blazor.LocaleTranslations embeds the Unicode CLDR zone names for every label-pack locale (all 64):

@using LilyDesignSystem.Blazor.LocaleTranslations

<TimeZonePicker Label="Fuseau horaire" Locale="fr" Names="@LocaleTranslations.ZoneNames("fr-001")" />

ZoneNames gives (Standard, Daylight) per zone, with a null daylight name for a zone that has one name all year; the daylight name is used while daylight time is in force at the picker's Date. A zone CLDR has no name for in that language is not in the dictionary and shows the platform's name, never another language's. Cornish, Scots and Wu have no CLDR zone names. See spec/zone-names.

Behaviour

• Order: by UTC offset ascending (UTC-11:00 first, UTC+14:00 last); ties by name (compared in locale), then by id. An id the runtime does not know is left out; a repeated id appears once.
• Initial value: value > stored zone (only if still offered) > defaultValue > the reader's own zone when listed, or its listed twin (same offset and name: Europe/Berlin → Europe/Paris) > UTC > the first zone.
• Date: offsets are fixed for the picker's date (read once when none is given) so an open list never re-sorts under the pointer. Pass a date to show the offsets for a specific day.
• SSR-safe: all DOM writes happen inside an effect; the zone list is computed without the DOM.

Accessibility

• WCAG 2.2 AAA target.
• APG listbox keyboard contract: ArrowDown / ArrowUp / Enter / Space open; arrows clamp; Home / End; PageUp / PageDown by ten; typeahead over the option text (type UTC+05 to reach it); Escape closes without changing the value; Tab closes and moves on.
• The offset is written in ASCII (UTC+05:30, hyphen-minus), so typeahead and screen readers read it the same everywhere; the zone name comes from Intl in the reader's language.
• A tooltip repeats the label on hover and focus, dismissable with Escape, and is not linked with aria-describedby.

Lily™ and Lily Design System™ are trademarks.