Duration View

DurationView is a headless read-only display of a length of time, in the consumer's words. It renders as a <time> element whose datetime is the ISO 8601 duration, so the length stays machine-readable while the reader sees words in their language. The TypeScript libraries export durationParts(), whose result Intl.DurationFormat turns into words, and htmlDuration().

Status: experimental — new, implemented and unit-tested in every headless library; not yet exercised in a composed flow.

Example

Show demo markup
<time class="duration-view" datetime="P3DT4H"><span class="screen-reader-span">Length of stay </span>3 days 4 hours</time>
Usage example
<DurationView
  label="Length of stay"
  value="3 days 4 hours"
  duration="P3DT4H"
/>
Show Svelte source
// In your Svelte component:
import DurationView from "lily-design-system-svelte-headless/components/DurationView/DurationView.svelte";

<DurationView>
  <!-- content -->
</DurationView>

Usage

<DurationView
  label="Length of stay"
  value="3 days 4 hours"
  duration="P3DT4H"
/>

Props

  • value: string (required) — the length of time as the consumer writes it
  • duration: string (required) — the same length as an ISO 8601 duration of days, hours, minutes and seconds, optionally negative; rendered as datetime
  • label: string (optional) — hidden text naming the value
  • ...restProps: any — additional HTML attributes spread onto the root

Keyboard Interactions

None. This is not an interactive component.

ARIA

  • No role and no aria-label; label renders as hidden text

When to Use

  • Use for a length of time: a length of stay, a wait, an infusion's run time, the time since a dose.
  • Use where software or a script needs the length as well as the reader: the datetime holds it exactly.
  • Use for a negative duration such as "3 days early", with the direction in the words.

When Not to Use

  • Do not use for a person's age — use age-view, whose units suit the age.
  • Do not use for a date or a time of day — use date-time-view.
  • Do not use for a length in years or months — they have no fixed length and are no datetime; use age-view or plain text.
  • Do not use for a countdown that changes every second — use timer.

Headless

This headless component ships zero CSS and decides nothing visual. The consumer provides all styling targeting the .duration-view class hook, and every word.

Styles

.duration-view and [data-negative].

Testing

  • datetime holds the duration and the words render
  • A negative duration has data-negative and its length as datetime
  • Years, months and weeks render no datetime
  • durationParts() and htmlDuration() are tested in the shared module

Advice

  • Write the words in the reader's language: new Intl.DurationFormat(locale, { style: "long" }).format(durationParts(iso)), leaving out negative.
  • Keep the units the record has: 90 minutes is not 1.5 hours, and Lily converts nothing.
  • Do not round a clinical duration for display without saying so.

Implementation Notes

  • Renders <time class="duration-view" datetime="P3DT4H"> with the consumer's words
  • duration takes days, hours, minutes and seconds (P3DT4H, PT90M): an HTML datetime takes no years, months or weeks, which have no fixed length, and no sign
  • A negative duration (-P3D) renders its length as datetime and adds data-negative; say the direction in the words ("3 days early")
  • A duration HTML cannot take renders no datetime and raises a development warning
  • Writes no words for units: format durationParts() with Intl.DurationFormat, or pass your own words

Related components

  • age-view — a person's age, in the units suited to it
  • date-time-view — a read-only display of a date and time
  • timer — a time that changes as the reader watches

References


Lily™ and Lily Design System™ are trademarks.

Canonical contract

Generated from this component's canonical metadata — the machine-checked source the implementations are held to.

Metadata

  • Component: duration-view
  • PascalCase: DurationView
  • Description: a length of time, as an ISO 8601 duration in a <time> element, shown in the consumer's words
  • Status: experimental — new, implemented and unit-tested in every headless library; not yet exercised in a composed flow
  • HTML tag: <time>
  • CSS class: .duration-view
  • Interactive: no

ARIA

  • No role and no aria-label; label renders as hidden text

Keyboard

  • Not interactive

Props

  • value: string (required) — the length of time as the consumer writes it
  • duration: string (required) — the same length as an ISO 8601 duration of days, hours, minutes and seconds, optionally negative; rendered as datetime
  • label: string (optional) — hidden text naming the value
  • ...restProps: any — additional HTML attributes spread onto the root

Markdown

This page as Markdown, for people and AI tools: duration-view.md