Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
43.3 KB
Raw Blame

schema_version: 3 template_version: 7 kind: component id: component:Timestamp authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-27 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/hooks/useClipboard.test.tsx, .github/visual-baseline/manifest.json, packages/core/src/Timestamp/Timestamp.test.tsx, packages/core/src/Timestamp/tooltipEntries.test.ts, packages/core/src/theme/themingTargets.test.ts, apps/storybook/stories/Timestamp.stories.tsx, scripts/check-knowledge.mjs, ] modules: [] families: [] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:internationalization, architecture:public-component-api, architecture:react-component-runtime, architecture:icon-resolution-and-component-slots, ] contributing: []

system_specs: [spec:AST-009, spec:AST-013/FR12, spec:AST-085, spec:AST-111/FR18]

Timestamp component contract

Contract at a glance

Area Contract
Public contract A time element for a value (Unix seconds, milliseconds, or ISO 8601) in one of twelve formats, with optional live updates, time-zone suffix, and a copyable hover card.
Behavior Relative output carries the full absolute date as its default accessible name; relative output, or configured tooltipEntries, attach a keyboard-reachable hover card of copyable rows.
End-user impact Readers see compact or exact times in their locale; screen-reader users hear the full date and time zone; keyboard users can open and copy the exact time.
Builder impact Optional: set calendar on the InternationalizationProvider to write dates in another calendar. Optional: map the hover card's copy glyph through the timestamp-copy icon slot (FR10).
Compatibility/readiness No prop or default changes; FR10 adds the opt-in timestamp-copy theme slot, which is current and awaits implementation. Without a provider calendar the output is unchanged; under one, date-bearing formats change calendar, and calendars that need Temporal fall back to Gregorian where it is missing (the spec:AST-013 FR12 exception). A provider locale with a -u-ca- keyword keeps Gregorian dates (spec:AST-111 DEC-2); set the provider's calendar to choose one. One implementation gap is listed under Current-state impact.
Review checks Reject a relative timestamp without the full absolute name when the caller names nothing, a hover card without a tab stop, a change that makes more server markup depend on the server's zone, or a crash on an unparseable value.
Governing rules architecture:internationalization/INV4,INV8,INV10; spec:AST-111/FR18; spec:AST-013 FR12; architecture:react-component-runtime/INV1,INV3,INV5; architecture:public-component-api/INV5,INV6,INV8; architecture:icon-resolution-and-component-slots/INV2,INV4–INV8.

This table is a review projection; the body below is authoritative.

Intent

Timestamp shows one instant as human-readable text with machine-readable semantics. It owns choosing and formatting the display, keeping relative output current, the accessible name, and the hover card that reveals and copies the exact time.

Compatibility and migration

  • Released default preserved: yes
  • Compatibility class: no public prop, default, DOM, or styling change; date-bearing text follows the provider's calendar, which is Gregorian unless the application selects another. A provider locale with a -u-ca- keyword keeps Gregorian dates (spec:AST-111 DEC-2); set the provider's calendar to choose one
  • Controlled/uncontrolled behavior: not applicable; the current clock is internal state
  • Additive theme surface (FR10): a theme may map the copy glyph through componentIcons['timestamp-copy']; with no entry, the glyph is unchanged.
  • Migration decision: none

Consumer migration instructions belong in consumer docs and release notes.

Current-state impact

  • Absolute formats depend on the server's zone (FR3). An absolute format other than unix_seconds renders in the host's time zone unless the caller passes timezoneID, so without it the same instant reads "Mar 25" from a UTC server and "Mar 26" from a Tokyo server, and a viewer in another zone gets a hydration text mismatch. An explicit timezoneID pins the rendering on the server and the client alike.

Ownership boundary

Owns

  • The time element, its datetime attribute, and the Text wrapper carrying the timestamp target.
  • Value parsing, format selection, formatting, the time-zone suffix, and live updates.
  • The accessible name of relative output.
  • The hover card's rows, layout, copy buttons, and copy announcement.

Does not own / non-goals

  • Hover card opening, placement, and dismissal — owned by HoverCard.
  • Typography — delegated to component:Text.
  • Locale and calendar resolution — owned by architecture:internationalization helpers.
  • Clipboard writing and its live-region announcement mechanics — owned by the shared clipboard hook.

Public concepts

Concept Closed values or states Meaning Availability by variant/orientation/state Default Owner Stability Invalid-value behavior
Value Unix seconds (below 10¹²), Unix milliseconds, or an ISO 8601 string The instant shown. Always Required component:Timestamp Stable An unparseable value renders nothing and warns in development.
Format relative, relative_short, auto, date, date_long, date_weekday, date_time, time, system_date, system_date_time, system_time, unix_seconds How the instant is written. Always auto component:Timestamp Stable TypeScript rejects other values.
Hover card rows default (one copyable full-date row); configured tooltipEntries What the hover card shows; each row may opt into copying. Relative output, or any output with entries default component:Timestamp Stable An empty entry list counts as no configuration.
Live on; off Whether relative output refreshes. Relative output off component:Timestamp Stable —

Behavioral and layout contract

ID Invariant Basis
FR1 Timestamp renders a Text element (default type="supporting", color="secondary", with size and weight passed through) carrying the timestamp target, which reflects the resolved format beside Text's type and color reflection; inside it an inline time element inherits the typography and carries the instant's ISO 8601 datetime. An unparseable value renders nothing and logs a development warning. Current source and tests
FR2 auto shows relative when the instant is within autoThreshold seconds of now (default seven days) and date_time otherwise. relative uses the locale's long relative phrase and relative_short its narrow phrase; a value a few seconds in the future reads as "now". Absolute formats use the shared instant formatter in the provider locale. The date-bearing formats (date, date_long, date_weekday, date_time, and the full date of FR5 and FR7) write the date in the calendar that the provider resolves (spec:AST-111 FR2, FR5, FR18), which is Gregorian unless the application selects another; a locale's default calendar never applies, and date_time keeps its time of day. Each names the month and day that component:Calendar shows. time, the relative formats, system_*, and unix_seconds do not depend on the calendar. system_* formats are machine-readable Gregorian ISO, and unix_seconds is zone-independent. isTimezoneShown appends the zone abbreviation to date_time and time only. Current source and tests
FR3 Server markup does not depend on the server's time zone and hydrates without a mismatch. A format that needs the clock renders date_time in UTC and the Gregorian calendar with the zone shown until the client can read the clock; the client then shows the resolved format without committing the UTC placeholder. A calendar that needs Temporal hydrates without a mismatch only when the server and the browser resolve it the same way (the spec:AST-013 FR12 exception). Implementation gap: absolute formats other than unix_seconds render in the host's time zone unless the caller passes timezoneID, so without it their server markup depends on the server's zone and hydrating it in another zone produces a text mismatch (Current-state impact). Current source and tests
FR4 With isLive and relative output, the clock refreshes every second under a minute old, every 30 seconds under an hour, every minute under a day, and every five minutes beyond; the timer is cleared on unmount or when the inputs change. Locale changes update the output live. Current source and tests
FR5 Relative output is named by the full absolute date and the long time-zone name unless a caller names the element; absolute output adds no name. A caller's explicit aria-label reaches the element (architecture:public-component-api INV5). Current source and tests
FR6 When hasTooltip is true and the output is relative or tooltipEntries is non-empty, a lazily loaded HoverCard named "Timestamp details" attaches above the timestamp, opening on hover and on keyboard focus; the time element gains tabIndex={0}. Otherwise no card renders and no tab stop is added. Focus placed on the timestamp stays there when the card attaches (spec:AST-085 FR4). Current source and tests
FR7 The card is a description list in a grid: an optional label column (present when any row has a label), the value column, and a trailing action column (present when any row is copyable). Without entries it has one copyable row with the full absolute time in the viewer's zone. Each configured entry is one row in the given order, rendered in its own time zone and format, read-only unless isCopyable. An entry without its own timezoneID renders in the Timestamp's timezoneID when one is set, else the viewer's zone. An unknown time zone does not crash. A description list holds only name-value groups (WCAG 2.2 1.3.1). Each row is a name-value group; a row without a label is named by its time zone's long name, which is visually hidden. A copy button sits inside its row's value. Current source and tests
FR8 A copy button is a small ghost IconButton on the timestamp-copy-button target, named "Copy {value}" with a "Copy" tooltip; activating it writes the row's value to the clipboard, switches to the copied glyph (check unless a theme maps timestamp-copy, FR10) and the "Copied" name and tooltip for 1.5 seconds, and announces "Copied" politely. A clipboard rejection does nothing. Current source and tests
FR9 ref, data-testid, and other supported DOM, ARIA, data, and event props reach the time element; xstyle, className, and style reach the Text wrapper. A caller aria-labelledby names the element in place of FR5's name. A caller's explicit tabIndex reaches the element (architecture:public-component-api INV5). Current source and tests
FR10 The copy button's glyph resolves through the timestamp-copy component icon slot, passing {copied}, which is true while the copied state (FR8) shows. With no theme entry, the glyph is copy, and check while copied. When the slot resolves to no icon (a theme value of null, a slot function that returns null, or a request with icon: null), only the glyph is hidden: the button keeps its size, name, tooltip, and copy behavior, and shows no glyph at rest or while copied. A request size changes only the glyph, never the button. Proposal; architecture:icon-resolution-and-component-slots/INV2,INV4–INV8

Allowed variation

  • AV1 — Locale wording. Phrases, month names, and zone names follow the provider locale.
  • AV2 — Theme paint. A theme may restyle timestamp per format, type, and color, and timestamp-copy-button, without changing the output text.

Representative states

State Required invariant Allowed variation
Relative, recent Relative phrase; full-date name; tab stop; hover card with one copyable row. Locale.
Auto, old date_time; no name; no card unless entries are configured. Threshold.
Absolute with entries Card attached with configured rows; tab stop; no added name. Entries.
Server render Markup identical across server zones; clock-dependent formats show UTC date_time with zone (absolute formats use the server's zone today, the FR3 gap). —
Live Relative phrase refreshes at the tier's interval. —
Unparseable Nothing rendered; development warning. —
Provider calendar Date-bearing output, the card's full date, and the relative name in that calendar; date_time keeps its time; system_* stays Gregorian ISO. Calendar, locale.
hasTooltip={false} No card and no tab stop, even with entries. —

Transformation and precedence order

  • ORD1 — Display format. Clock pending → UTC date_time; else auto → relative or date_time by threshold; else format.
  • ORD2 — Card rows. Non-empty tooltipEntries → the default full-date row.
  • ORD3 — Time element attributes. datetime and data-testid are set, then caller props; the relative name and the card's tab stop apply only where the caller sets no aria-label or tabIndex.

Performance and resources

  • PR1 — Bounded work. Only relative output with isLive runs a timer, at most one per instance, cleared on change or unmount; the hover card module loads only when a card is attached; copy state exists only for copyable rows.

Accessibility contract

  • AR1 — Machine-readable instant. The time element carries the ISO 8601 instant in datetime.
  • AR2 — Full name for relative output. Relative output is named by the full absolute date with the spelled-out time zone (WCAG 2.2 3.1.4).
  • AR3 — Keyboard-reachable card. While a card is attached the timestamp is a tab stop and the card opens on focus. Without a card there is no tab stop. The focusable time is the card's anchor and keeps focus while the card loads and attaches. While the card is open, the time names it through aria-controls; it carries no aria-haspopup or aria-expanded, which the time role does not support. Hover and focus on the time open the card; empty layout space around it does not.
  • AR4 — Copy feedback. Copy buttons are named with their value, and a copy is announced politely.

Design relationships

Anatomy or state Design requirement Representation authority Hierarchy role Component contract
Formatted text The instant in compact or exact form, in supporting type by default. Current source and docs Prominent FR1–FR5
Hover card A copyable card with the exact time or configured rows. Current source and docs Supporting FR6, FR7, AR3
Hover card row An optional label beside one rendering of the instant. Current source and docs Supporting FR7
Copy button Copies one row's value with brief confirmation. Current source and docs Supporting FR8, FR10, AR4

Theming anatomy

{
  "Formatted text": {"target": "timestamp"},
  "Hover card": {
    "delegatesTo": {"owner": "component:HoverCard", "target": "hover-card"}
  },
  "Hover card row": {
    "none": {
      "reason": "reachability-gap: rows render inside the hover card content without a component-owned class"
    }
  },
  "Copy button": {"target": "timestamp-copy-button"}
}

Family and system relationships

  • architecture:internationalization owns locale resolution, live locale changes, the shared formatter, and calendar resolution with its Gregorian default; spec:AST-111 FR18 sets which formats follow the calendar. FR2 and FR4 rely on them.
  • architecture:react-component-runtime owns valid initial render and timer cleanup; FR3 and FR4 apply them.
  • HoverCard owns the card surface; Timestamp supplies its content, name, and trigger focusability.

spec:AST-013 FR12 exception — calendars that need Temporal

  • Capability: date-bearing output in calendars other than gregory, iso8601, buddhist, roc, and japanese, which need the runtime's Temporal.
  • Reduction: where Temporal is missing or does not support the calendar, as in Safari on macOS and iOS, such a calendar resolves to gregory before the first render and warns once in development, on the server and in the browser, naming temporal-polyfill/full/global (spec:AST-111 FR5). The date-bearing formats, the card's full date, and the relative name then write Gregorian dates. An application that loads a Temporal polyfill gets the full calendar. A server without Temporal renders Gregorian text, which a browser with Temporal does not match, so a server-rendered application loads Temporal on the server too.
  • Preserved obligations: spec:AST-013 FR7 and FR8, and FR9 whenever the server and the browser resolve the calendar the same way, outside the chinese and dangi case of spec:AST-111 FR19. The Gregorian output keeps the instant, its accessible name, the hover card, and copying; nothing throws.
  • Evidence: Timestamp.test.tsx calendar-system tests with a Temporal polyfill and with Temporal removed, and "hydrates a clock format rendered on a server without Temporal". Evidence gap: no real-browser run, and no hydration test of an absolute date format, under a calendar that needs Temporal.
  • Owner: nynexman4464.
  • Review condition: Safari ships Temporal.

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
FR1, FR2 Timestamp.test.tsx format, auto, locale, calendar-system, and invalid-value tests; tooltipEntries.test.ts calendar tests; stable visual baseline core-timestamp--default Every format; thresholds; locales; persian, hebrew, and buddhist under English and native locales, with and without Temporal; iso8601; chinese where Intl and Temporal disagree; unparseable values; default A wrong phrase, a crossed tier, a non-Gregorian year without a provider calendar, a date-bearing format that ignores the provider calendar or names another day than component:Calendar, a changed system_* or time output, a missing time element or datetime, a crash, or a missing development warning for an unparseable value fails; a changed default type or color comes back changed for review. Gap: no test asserts the timestamp target or its format reflection. audit:Timestamp/behavior
FR3 Timestamp.test.tsx server-rendering suite and "hydrates a clock format rendered on a server without Temporal" Server zones; hydration Zone-dependent markup, a hydration mismatch, or a committed placeholder fails. Gap: no test covers an absolute format rendered on a server in another zone. audit:Timestamp/behavior
FR4, PR1 Timestamp.test.tsx live-update and locale tests Live relative output; locale change A missing refresh or a stale locale fails. Gap: the per-tier refresh intervals and the timer cleanup on unmount or input change have no automated check. audit:Timestamp/behavior
FR5, AR2 Timestamp.test.tsx naming tests Relative, absolute, time-zone spelling A missing or short-zone name, or a name on absolute output, fails. A caller aria-label replaced on relative output fails. audit:Timestamp/a11y
FR6, AR3 Timestamp.test.tsx keyboard-reachability suite; Timestamp.a11y.browser.spec.ts (Chromium and WebKit): focus stays on the time across the lazy attach, aria-controls names the open card, and axe passes Relative, absolute, disabled, entries removed A missing tab stop, aria-expanded on the trigger, or a stray tab stop fails. audit:Timestamp/a11y
FR7, FR8, AR4 Timestamp.test.tsx hover-card suites, including "keeps a copyable labelled card a valid description list" and the default card's hidden zone name; tooltipEntries.test.ts; useClipboard.test.tsx Default row, entries, copyable rows, unknown zone A wrong row count or order, an unpaired label, a copy button on a read-only row, a wrong copied value, a missing copied state, or a missing announcement fails. Gap: no check runs the definition-list structure rule on the open card; the grid columns and the 1.5-second reset have no automated check; useClipboard.test.tsx covers the clipboard-rejection no-op. audit:Timestamp/behavior
FR9 Timestamp.test.tsx ref, test-id, and pass-through tests Ref, test id, caller props A ref, test id, or caller prop missing from the time element fails. A caller tabIndex replaced while a card is attached fails. Gap: no test asserts that xstyle, className, and style reach the Text wrapper, or covers a caller aria-labelledby. audit:Timestamp/behavior
FR10 Timestamp.test.tsx copy icon slot suite; the slot inventory test No entry, a slot function in both states, null, a size request The glyph ignores the slot or its state, null removes the button, its name, or its copy action, a size request resizes the button, or the consumer docs do not list the slot. audit:Timestamp/theming
Theming anatomy map scripts/check-knowledge.mjs Consumer anatomy, targets, HoverCard delegate Missing, extra, or stale mappings fail repository validation. audit:Timestamp/theming
AR1 Timestamp.test.tsx datetime tests date_time; date A missing or wrong ISO datetime on date_time, or a missing one on date, fails. Gap: no test asserts the exact datetime on relative or other absolute formats. audit:Timestamp/a11y
AR2, AR4 Accessibility-tree evidence (spec:AST-009 FR3) Relative output; copy buttons Gap: no accessibility-tree check proves the computed name of relative output or the copy-button names; the unit tests query the DOM. audit:Timestamp/a11y

Decision log

None recorded. The record describes shipped behavior.

Open questions

None.

Content boundary

This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.