feat: initial implementation

[paodb]

Relative Time Add-On: initial implementation

Implements the RelativeTime component: a thin Vaadin Flow wrapper around the @github/relative-time-element web component (v5.0.0). It renders a date/time as a human-readable relative string ("4 hours ago", "in 2 weeks") that updates itself in the browser as time passes.

Component API

RelativeTime extends Component, configured through a fluent, typed Java API:

• Target date: 5 setDateTime overloads + 6 constructors accepting Instant, OffsetDateTime, ZonedDateTime, LocalDateTime, LocalDate (the local types interpreted in the server's default zone). getDateTime() returns the last value as a UTC Instant.
• Relative-format controls: setTense, setFormat, setPrecision, setFormatStyle, setThreshold(Duration), setPrefix, setNoTitle, setLocale.
• Absolute-format controls (apply when format=DATETIME): setTimeZone(ZoneId), setTimeZoneName, and per-part formatting setters setYear/setMonth/setDay/setWeekday/setHour/setMinute/setSecond.
• All reference-typed setters accept null to clear; all return this for chaining.
• Six enums map one-to-one to the upstream attribute vocabulary: Tense, Format, Precision, FormatStyle, TimeZoneName, DateTimePartStyle.

The wrapper drives the element via HTML attributes (not DOM properties), matching the upstream's attribute-driven design. This is documented in the class Javadoc and spec so it isn't accidentally "modernised."

Compatibility & theming

• Vaadin 24 and 25 (verified by running the test suite under both the default and v25 profiles).
• Theme-agnostic: the component is inline text inheriting from its parent; demo styles use a Lumo / Vaadin-base / literal CSS fallback chain so they render under Lumo, Aura, and the bare base theme.

Tests

• RelativeTimeTest: 19 unit tests covering every setter's attribute output, conversions, null-clearing, and fluent return.
• SerializationTest: empty + fully-configured instances.
• ViewIT: integration test; matcher updated to detect upgrade via shadow-root text content (relative-time renders text, not child elements).

Demos

Two tabs sharing an AbstractRelativeTimeDemo base (separator + section-highlight helpers):

• Basic Demo: feature-by-feature (threshold, format style, live update, localisation, prefix), plus Past/Future date matrices mirroring the upstream examples page. Hover-to-highlight source fragments.
• Use Cases: realistic patterns (audit-log Grid, chat bubbles, event card, date-picker preview, live stopwatch, session-expiry banner).

Adds SPECIFICATIONS.md documenting the full API, defaults, live-update behaviour, and known upstream quirks.

🤖 Generated with Claude Code

[paodb]

Requesting review @javier-godoy@scardanzan

[javier-godoy]

Code review — automated (recall-oriented)

Reviewed the full diff and verified the entire attribute vocabulary against the upstream @github/relative-time-element v5.0.0 source (format, tense, precision, format-style, time-zone/time-zone-name, per-part attributes, prefix, no-title, isDuration, shadow-root rendering). All enum→attribute mappings match upstream and all written attributes are in upstream's observedAttributes.

Verdict: a clean, well-tested thin wrapper — no functional bug in the core mapping logic. The items below are one real validation gap, a misleading HasSize, two doc-vs-code contradictions, and some edge/cleanup nits. Inline comments mark each location.

Findings (ranked)

1. Per-part setters don't validate the part/style subset → invalid values silently dropped/coerced in the browser. (correctness — RelativeTime.setWeekday et al.)
2. setTimeZone(ZoneId) with a ZoneOffset/legacy zone emits +02:00/GMT+02:00 → client RangeError; no IANA guard. (correctness, edge)
3. HasSize is a no-op on the inline host; SPEC §5 wrongly advertises it for layout. (API/doc)
4. Javadoc + SPEC §2.2 claim offset/zone is "preserved on the wire string" — false; normalized to UTC via toInstant(). (doc contradiction)
5. SPEC §2.4 // → threshold="P30D" is wrong; Duration.ofDays(30).toString() = PT720H. (doc error)
6. setDateTime(null) is ambiguous across 5 overloads → won't compile without a cast; no clear(). (ergonomics)
7. setLocale(Locale.ROOT) → lang="und", silent fallback, undocumented. (edge)
8. Negative Duration threshold → PT-nS rejected by upstream isDuration → silent revert to default P30D. (edge)
9. Identical attributeValue() duplicated across 4 enums. (cleanup)
10. setNoTitle is the one setter that bypasses the setOrRemove helper. (cleanup)

Spec text to change

• §2.7 ("invalid combinations… silently falls back") describes a gap to close (#1), not a contract.
• §5 HasSize claim is inaccurate (#3).
• §2.2 offset/zone rows and §2.4 P30D example are wrong (#4, #5).

Checked & not issues

@CssImport("./styles/…") path (correct for META-INF/frontend); IT navigation/matcher; stopwatch button text; session-expiry double Instant.now() (intentional); duplicate AppShellConfigurator (only one — standard FC idiom); pom.xmlscanIntervalSeconds→scan (both 0 = disabled; correct Jetty 12 param).

Recommendation: approve with changes — fix #1 and decide #3; correct the docs for #4/#5.

[javier-godoy]

@javier-godoy — ready for human review. 🙋

Re-reviewed the pushed fixes (incremental diff 3e586d3..HEAD, +186/−35) and verified them:

• 9 of 10 original findings resolved — their review threads are now replied-to and marked resolved. Finding 1 (per-part validation) was the substantive one and is correctly implemented (setDatePart + allowed-style sets, subsets match Intl.DateTimeFormat, tests added).
• No caller regressions from the HasSize removal, and the new setTimeZone/setThreshold/per-part validation doesn't throw on any existing demo or test call (all use allowed values). Confirmed UTC/America/New_York ∈ getAvailableZoneIds(), offsets ∉.
• 1 thread left open — Finding 10 (setNoTitle doesn't route through setOrRemove), deferred as lowest-priority cleanup.

Remaining notes are all low-severity polish (none blocking): a Javadoc caveat + caching for the timezone check, wrapping ALL_STYLES as immutable, and adding clear() to the fluent-chain test. Details are in the resolved threads.

My automated assessment: approve pending your call on the open item and the polish notes. Over to you for human review.