Skip to the content

Props

NameTypeDefaultDescription
sources*readonly [SourceLineSource] | readonly [SourceLineSource, SourceLineSource]—Where the panel's data comes from, one source or two, each with its own name and the time of its data, and what that time is of when the app words it, in the order the line shows them. Required. Each source keeps its own time: the line never joins two into one "last updated" (CR-4).
pausedbooleanfalseThe panel takes no updates for now: the line starts with "Paused", and each time stays the time of the data the panel shows (CR-5).
sourceUpdatedLabelstringThe locale'sOverrides "updated {time}", the phrase that gives each source's time; {time} is filled with the source's time
sourcePausedLabelstringThe locale'sOverrides "Paused", the word that starts a paused line
sourceOutOfDateLabelstringThe locale'sOverrides "updated {time}, may be out of date", the phrase that gives the time of a source whose outOfDate is set; {time} is filled with the source's time
sourceLabelOutOfDateLabelstringThe locale'sOverrides "{label}, may be out of date", the phrase that gives the time of a source with its own label whose outOfDate is set; {label} is filled with that label, its {time} filled with the source's time
classNamestring—Joined after pn-Text pn-SourceLine on the root
styleCSSProperties—Reaches the root
refRef<HTMLParagraphElement>—Reaches the root element
slotProps{ paused?: DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> | undefined; source?: DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> | undefined; name?: DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> | undefined; separator?: DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> | undefined; time?: DetailedHTMLProps<TimeHTMLAttributes<HTMLTimeElement>, HTMLTimeElement> | undefined; }—Props for each part: paused, source, name, separator, time.
sources (required)readonly [SourceLineSource] | readonly [SourceLineSource, SourceLineSource], default —
Where the panel's data comes from, one source or two, each with its own name and the time of its data, and what that time is of when the app words it, in the order the line shows them. Required. Each source keeps its own time: the line never joins two into one "last updated" (CR-4).
pausedboolean, default false
The panel takes no updates for now: the line starts with "Paused", and each time stays the time of the data the panel shows (CR-5).
sourceUpdatedLabelstring, default The locale's
Overrides "updated {time}", the phrase that gives each source's time; {time} is filled with the source's time
sourcePausedLabelstring, default The locale's
Overrides "Paused", the word that starts a paused line
sourceOutOfDateLabelstring, default The locale's
Overrides "updated {time}, may be out of date", the phrase that gives the time of a source whose outOfDate is set; {time} is filled with the source's time
sourceLabelOutOfDateLabelstring, default The locale's
Overrides "{label}, may be out of date", the phrase that gives the time of a source with its own label whose outOfDate is set; {label} is filled with that label, its {time} filled with the source's time
classNamestring, default —
Joined after pn-Text pn-SourceLine on the root
styleCSSProperties, default —
Reaches the root
refRef<HTMLParagraphElement>, default —
Reaches the root element
slotProps{ paused?: DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> | undefined; source?: DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> | undefined; name?: DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> | undefined; separator?: DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> | undefined; time?: DetailedHTMLProps<TimeHTMLAttributes<HTMLTimeElement>, HTMLTimeElement> | undefined; }, default —
Props for each part: paused, source, name, separator, time.

Use it

import { SourceLine } from '@mylder/perron/patterns'

Ask your agent

search_docs({ query: "SourceLine" })

Keyboard and ARIA

SourceLine has no keys of its own and nothing in it is focusable: it is read, not operated.

KeyDoesFrom
TabPasses the line by to the next focusable element: it has no tab stop (CR-8)Perron
ElementRoleAccessible name fromStates announced
rootparagraph, from the native <p>None; its text is read in placeNone
pausedNone: a generic <span>Not named; "Paused" is read in placeNone
sourceNone: a generic <span>Not named; its text is read in placeNone
nameNone: a generic <span>Not named; read in placeNone
separatorNone: a generic <span>Not named; "·" is read as the reader reads itNone
timetime, from the native <time>; none, a generic <span>, for a phrase that shows no timeNot named; its phrase is read in placeNone

A line reads "Rejseplanen · updated 08:14:05", and a paused one with a doubtful second source "Paused · Rejseplanen · updated 08:14:05 · Vehicle positions · updated 08:09:40, may be out of date". In the app's words: "Rejseplanen · position 08:14:05 · times 08:14:20, may be out of date". A phrase that shows no time, "times from the timetable", or "departures —" while its time is unknown, is the same time part as a <span>: a <time> must carry a date or time, in its dateTime or its text, and a dateTime the phrase doesn't show would tell the ear's tools what the eye isn't told.

The line is no live region: its times change in place without an announcement. The times change every few seconds, which would flood a screen reader, and Accessibility asks that only changes of state be announced, in the screen's own polite live region; a screen that must say a source went out of date or the panel paused says it there.

What axe won't catch, from the contract, each with how this component meets it:

  • Everything the eye is told, the ear is told, for every shape each prop accepts: every part is text read in place, the "·" included; paused and out of date are words, not only colours (CR-5, CR-6); nothing is aria-hidden.
  • Every landmark and named region has an accessible name: none here; the line is a paragraph, not a landmark or region.
  • Every default label can be overridden: sourceUpdatedLabel, sourcePausedLabel, sourceOutOfDateLabel and sourceLabelOutOfDateLabel, the first two phrases with the same {time} placeholder and the last with {label}; and a source's own label overrides "updated {time}" for that source.
  • Every shape the type accepts renders, in every variant: sources with one source and with two, each with outOfDate left out, false and true, with paused off and on, a time as HH:MM:SS, as HH:MM and as a date with its dateTime, a source with and without a name, with and without a label, a label with no {time}, with and without a time, a label with {time} and no time, and a name of one long word; every *Label string replaces only its own words. SourceLine takes no ReactNode.
  • A hidden copy kept for animation is aria-hidden, and a collapsed region is inert: none here; nothing animates or collapses.
  • Native semantics first: a <p> from Text, <span>s, and a <time> per source whose phrase shows a time; no ARIA of the pattern's own.
  • Focus moves in reading order and returns on close: nothing takes focus or opens; Tab passes the line by.
  • Every target is at least size.target-min square: no target; nothing in the line is pressed.
  • Loops stop when the system asks for less motion: none here; nothing moves, and a time changes its text without a transition.

Owned strings

Four keys, each in packages/perron/src/locale/en.ts and the Danish, Swedish and Norwegian dictionaries, which agents write; sourceLabelOutOfDate joined the first three with the source's label. All four are named for the source line, since each is worded for it alone: a status line elsewhere, such as the TopBar's "Updated 08:14:05", needs a sentence-case "Updated" under a key of its own. The two phrases wrap the caller's time, so each is one string with a {time} placeholder, filled by interpolate, and its override takes the same placeholder (the contract's Words): Danish, Swedish and Norwegian put the time where their grammar needs it. Both phrases start in lower case because each sits inside the line, after a "·", as "min" and "to" sit inside theirs; "Paused" starts the line, in sentence case. sourceLabelOutOfDate wraps the caller's label filled with its time, so it starts with {label} and its own words follow in each locale, the same words sourceOutOfDate ends with. The names and labels are the caller's, the times are figures, and the "·" holds no letter, which expectOwnedStrings passes.

KeyEnglishOverrideSeen or heard where
sourceUpdatedupdated {time}sourceUpdatedLabelEach time part of a source that is not out of date, seen and read in place
sourcePausedPausedsourcePausedLabelThe paused part, first in a paused line, seen and read in place
sourceOutOfDateupdated {time}, may be out of datesourceOutOfDateLabelEach time part of a source whose outOfDate is set, seen and read in place
sourceLabelOutOfDate{label}, may be out of datesourceLabelOutOfDateLabelEach time part of a source with a label whose outOfDate is set, seen and read in place

Do and don't

For a caller using the pattern, with the reason. Each row is a rule: a must row's Don't is never right, a should row's needs a reason, and Checked by says what catches the Don't in a caller's code.

RuleLevelDoDon'tChecked by
DD-1mustPut a SourceLine on every panel that shows a source's data, in the same place, so the reader finds it on every screenLeave the line off a panel because another panel on the screen has one: Rejseplanen's terms ask for it on every screenreview
DD-2mustGive each source its own entry with the time of its own dataPass one source named "Rejseplanen and positions" with one time: a stale feed would read as fresh under the other's timereview
DD-3mustWord each time by what it is of in label, "position {time}", and leave name off a second fact of the same providerWrite "may be out of date" into a label, or pick the label by outOfDate: set outOfDate and the line adds its own wordsreview
DD-4mustGive the time of the data the panel shows, and give it again when that data changesGive the time the screen last rendered, or the device's clock: the line would say the data is newer than it isreview
DD-5mustSet outOfDate from the app's own judgement, such as a failed refresh or a time past its limitLeave a source that failed to refresh without outOfDate: its time alone doesn't tell the reader it stoppedreview
DD-6mustSet paused while the panel takes no updates, and leave each time as it wasCount the time up, or show "8 s ago", while paused: the line would claim a freshness the panel doesn't havereview
DD-7mustAnnounce a change of state, such as a source going out of date, in the screen's own polite live regionMake the line a live region: its times change every few seconds and would flood a screen readerreview
DD-8shouldCredit a map's sources with Attribution, with links to their termsUse the line for the map's credits: it names the data a panel shows and when, not the map's tilesreview