Package com.flowingcode.vaadin.addons.relativetime

Class RelativeTime

java.lang.Object

com.vaadin.flow.component.Component

com.flowingcode.vaadin.addons.relativetime.RelativeTime

All Implemented Interfaces:

AttachNotifier, DetachNotifier, HasElement, HasStyle, Serializable

@Tag("relative-time")
@NpmPackage(value="@github/relative-time-element",
            version="5.0.0")
@JsModule("@github/relative-time-element")
public class RelativeTime
extends Component

Renders a date/time as a human-readable relative string ("4 hours ago", "in 2 weeks") that updates in the browser as time passes and is shown in the viewer's local time.

Thin wrapper around the @github/relative-time-element custom element. The Java setters write the corresponding attributes on the element and the browser does all the formatting and updating work.

Client-side rendering. The rendered text reflects the viewer's clock and locale, not the server's. There is no server-side API to read the displayed string; the string lives only in the DOM.

Attributes, not properties. Setters write HTML attributes (setAttribute), not DOM properties, because the upstream element is attribute-driven and its kebab-case attribute names match the upstream docs one-to-one. setProperty would force diverging camelCase names.

LocalDateTime and LocalDate inputs are interpreted in the server's default zone before being serialised as an instant.

See Also:

• Serialized Form

Constructor Summary

Constructors

Constructor	Description
RelativeTime()	Creates an empty component.
RelativeTime(Instant datetime)	Creates a component bound to the given instant.
RelativeTime(LocalDate date)	Creates a component bound to midnight of the given date, in the server's default zone.
RelativeTime(LocalDateTime datetime)	Creates a component bound to the given local date-time, interpreted in the server's default zone.
RelativeTime(OffsetDateTime datetime)	Creates a component bound to the given offset date-time.
RelativeTime(ZonedDateTime datetime)	Creates a component bound to the given zoned date-time.

Method Summary

Modifier and Type	Method	Description
RelativeTime	clear()	Clears the target datetime: removes the datetime attribute and the component renders as empty.
Instant	getDateTime()	Returns the last instant applied via any of the setDateTime overloads, normalised to UTC.
RelativeTime	setDateTime(Instant datetime)	Sets the target instant.
RelativeTime	setDateTime(LocalDate date)	Sets the target to midnight of the given date, in the server's default zone.
RelativeTime	setDateTime(LocalDateTime datetime)	Sets the target as a LocalDateTime, interpreted in the server's default zone.
RelativeTime	setDateTime(OffsetDateTime datetime)	Sets the target as an OffsetDateTime.
RelativeTime	setDateTime(ZonedDateTime datetime)	Sets the target as a ZonedDateTime.
RelativeTime	setDay(DateTimePartStyle style)	Sets the day attribute.
RelativeTime	setFormat(Format format)	Sets the format attribute (default auto, which is an alias for Format.RELATIVE).
RelativeTime	setFormatStyle(FormatStyle style)	Sets the format-style attribute.
RelativeTime	setHour(DateTimePartStyle style)	Sets the hour attribute.
RelativeTime	setLocale(Locale locale)	Sets the lang attribute from a Locale (rendered as a BCP 47 language tag).
RelativeTime	setMinute(DateTimePartStyle style)	Sets the minute attribute.
RelativeTime	setMonth(DateTimePartStyle style)	Sets the month attribute.
RelativeTime	setNoTitle(boolean noTitle)	When true, adds the no-title attribute, suppressing the automatic absolute-date tooltip.
RelativeTime	setPrecision(Precision precision)	Sets the precision attribute (default second).
RelativeTime	setPrefix(String prefix)	Sets the prefix attribute (default "on"), the word prepended to absolute dates when the relative-format threshold is crossed.
RelativeTime	setSecond(DateTimePartStyle style)	Sets the second attribute.
RelativeTime	setTense(Tense tense)	Sets the tense attribute (default auto).
RelativeTime	setThreshold(Duration threshold)	Sets the threshold attribute as an ISO-8601 duration (P30D, PT24H).
RelativeTime	setTimeZone(ZoneId timeZone)	Sets the time-zone attribute from a ZoneId (e.g.
RelativeTime	setTimeZoneName(TimeZoneName value)	Sets the time-zone-name attribute, controlling whether and how the time-zone name is appended in absolute-date output.
RelativeTime	setWeekday(DateTimePartStyle style)	Sets the weekday attribute.
RelativeTime	setYear(DateTimePartStyle style)	Sets the year attribute.

Methods inherited from class com.vaadin.flow.component.Component

addListener, findAncestor, fireEvent, from, get, getChildren, getElement, getEventBus, getId, getListeners, getLocale, getParent, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onAttach, onDetach, onEnabledStateChanged, removeFromParent, scrollIntoView, scrollIntoView, set, setElement, setId, setVisible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.vaadin.flow.component.AttachNotifier

addAttachListener

Methods inherited from interface com.vaadin.flow.component.DetachNotifier

addDetachListener

Methods inherited from interface com.vaadin.flow.component.HasStyle

addClassName, addClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName

Constructor Details

RelativeTime

public RelativeTime()

Creates an empty component. setDateTime(java.time.Instant) can be called later.

RelativeTime

public RelativeTime(Instant datetime)

Creates a component bound to the given instant.

RelativeTime

public RelativeTime(OffsetDateTime datetime)

Creates a component bound to the given offset date-time.

RelativeTime

public RelativeTime(ZonedDateTime datetime)

Creates a component bound to the given zoned date-time.

RelativeTime

public RelativeTime(LocalDateTime datetime)

Creates a component bound to the given local date-time, interpreted in the server's default zone.

RelativeTime

public RelativeTime(LocalDate date)

Creates a component bound to midnight of the given date, in the server's default zone.

Method Details

setDateTime

public RelativeTime setDateTime(Instant datetime)

Sets the target instant. null clears the datetime attribute and the component renders as empty.

setDateTime

public RelativeTime setDateTime(OffsetDateTime datetime)

Sets the target as an OffsetDateTime. The offset is applied via toInstant(); the wire string is the resulting UTC instant (the offset itself is not retained).

setDateTime

public RelativeTime setDateTime(ZonedDateTime datetime)

Sets the target as a ZonedDateTime. The zone is applied via toInstant(); the wire string is the resulting UTC instant (the zone itself is not retained).

setDateTime

public RelativeTime setDateTime(LocalDateTime datetime)

Sets the target as a LocalDateTime, interpreted in the server's default zone.

setDateTime

public RelativeTime setDateTime(LocalDate date)

Sets the target to midnight of the given date, in the server's default zone.

clear

public RelativeTime clear()

Clears the target datetime: removes the datetime attribute and the component renders as empty. Equivalent to setDateTime((Instant) null) but without the cast that the overloaded setDateTime(null) would otherwise require.

getDateTime

public Instant getDateTime()

Returns the last instant applied via any of the setDateTime overloads, normalised to UTC. Returns null if no datetime has been set or it was cleared.

setTense

public RelativeTime setTense(Tense tense)

Sets the tense attribute (default auto). Ignored when format is Format.DATETIME. null removes the attribute.

setFormat

public RelativeTime setFormat(Format format)

Sets the format attribute (default auto, which is an alias for Format.RELATIVE). null removes the attribute.

setPrecision

public RelativeTime setPrecision(Precision precision)

Sets the precision attribute (default second). Ignored when format is Format.DATETIME. null removes the attribute.

setFormatStyle

public RelativeTime setFormatStyle(FormatStyle style)

Sets the format-style attribute. The default depends on the format in effect: narrow for Format.ELAPSED/Format.MICRO, short for Format.DATETIME, long for Format.RELATIVE/Format.AUTO/Format.DURATION. null removes the attribute.

setThreshold

public RelativeTime setThreshold(Duration threshold)

Sets the threshold attribute as an ISO-8601 duration (P30D, PT24H). Default is P30D. Once the gap to the target exceeds this duration the element switches from a relative phrase to an absolute date. null removes the attribute.

Only consulted when format is Format.AUTO/Format.RELATIVE AND tense is Tense.AUTO. Pairing this with setTense(PAST) or setTense(FUTURE) silently makes the threshold inert, because the element then commits to relative phrasing regardless of distance.

Throws:

IllegalArgumentException - if threshold is negative. Java serialises a negative duration as PT-nS, which the upstream element's duration parser rejects, silently reverting to the default P30D. Zero is allowed (it means "always absolute").

setPrefix

public RelativeTime setPrefix(String prefix)

Sets the prefix attribute (default "on"), the word prepended to absolute dates when the relative-format threshold is crossed. Pass an empty string to drop the prefix entirely; null removes the attribute and restores the default.

setNoTitle

public RelativeTime setNoTitle(boolean noTitle)

When true, adds the no-title attribute, suppressing the automatic absolute-date tooltip. false removes it (the element's default behaviour shows the tooltip).

setLocale

public RelativeTime setLocale(Locale locale)

Sets the lang attribute from a Locale (rendered as a BCP 47 language tag). The browser uses Intl.RelativeTimeFormat / Intl.DateTimeFormat to localise the phrasing. null removes the attribute; when unset, the upstream walks DOM ancestors via closest('[lang]') and falls back to the document's lang, so an app-wide locale on <html lang="..."> is picked up automatically.

Note: Locale.ROOT (and new Locale("")) serialises to lang="und", which the browser treats as "undetermined" and silently resolves to the document/default locale, so passing the root locale looks like it was ignored. Pass null to clear instead.

setTimeZone

public RelativeTime setTimeZone(ZoneId timeZone)

Sets the time-zone attribute from a ZoneId (e.g. America/New_York). When set, the element formats the date in this zone instead of the viewer's. null removes the attribute; when unset, the upstream walks DOM ancestors via closest('[time-zone]') and falls back to the document's time-zone attribute (and, absent that, the browser default).

Throws:

IllegalArgumentException - if timeZone is not an IANA region zone. Offset-based zones (a ZoneOffset such as +02:00 or Z, or a GMT+02:00 form) are written verbatim into the attribute and rejected by the browser's Intl.DateTimeFormat with a RangeError, which breaks rendering. The accepted set is ZoneId.getAvailableZoneIds() (which includes UTC).

setTimeZoneName

public RelativeTime setTimeZoneName(TimeZoneName value)

Sets the time-zone-name attribute, controlling whether and how the time-zone name is appended in absolute-date output. Only relevant when format is Format.DATETIME. null removes the attribute.

setYear

public RelativeTime setYear(DateTimePartStyle style)

Sets the year attribute. Accepts DateTimePartStyle.NUMERIC or DateTimePartStyle.TWO_DIGIT. Only relevant when format is Format.DATETIME. null removes the attribute.

setMonth

public RelativeTime setMonth(DateTimePartStyle style)

Sets the month attribute. Accepts DateTimePartStyle.NUMERIC, DateTimePartStyle.TWO_DIGIT, DateTimePartStyle.NARROW, DateTimePartStyle.SHORT, or DateTimePartStyle.LONG. Only relevant when format is Format.DATETIME. null removes the attribute.

setDay

public RelativeTime setDay(DateTimePartStyle style)

Sets the day attribute. Accepts DateTimePartStyle.NUMERIC or DateTimePartStyle.TWO_DIGIT. Only relevant when format is Format.DATETIME. null removes the attribute.

setWeekday

public RelativeTime setWeekday(DateTimePartStyle style)

Sets the weekday attribute. Accepts DateTimePartStyle.NARROW, DateTimePartStyle.SHORT, or DateTimePartStyle.LONG. Only relevant when format is Format.DATETIME. null removes the attribute.

setHour

public RelativeTime setHour(DateTimePartStyle style)

Sets the hour attribute. Accepts DateTimePartStyle.NUMERIC or DateTimePartStyle.TWO_DIGIT. Only relevant when format is Format.DATETIME. null removes the attribute.

setMinute

public RelativeTime setMinute(DateTimePartStyle style)

Sets the minute attribute. Accepts DateTimePartStyle.NUMERIC or DateTimePartStyle.TWO_DIGIT. Only relevant when format is Format.DATETIME. null removes the attribute.

setSecond

public RelativeTime setSecond(DateTimePartStyle style)

Sets the second attribute. Accepts DateTimePartStyle.NUMERIC or DateTimePartStyle.TWO_DIGIT. Only relevant when format is Format.DATETIME. null removes the attribute.