Run Clock
The time left on the running block, readable across a room. It counts down, then counts up past the plan with a plus sign.
When to Use
Use when:
A block is running and the facilitator needs the time left at a glance: the cockpit, the run screen, Sidekick. Give it
endsAt and the clock keeps itself right from that timestamp.
Variants
Sizes
md is the run bar's size, lg (the default) the side panel's, xl the wide cockpit's.
07:20
left of 20 min
07:20
left of 20 min
07:20
left of 20 min
<?= ws_run_clock(['seconds' => 440, 'planned' => 20, 'size' => 'md']) ?> <?= ws_run_clock(['seconds' => 440, 'planned' => 20]) ?> <?= ws_run_clock(['seconds' => 440, 'planned' => 20, 'size' => 'xl']) ?>
The four states
Pass seconds and the state follows: the last two minutes are ending, anything below zero is over. Only paused is ever passed by hand.
07:20
left of 20 min
01:30
left of 20 min
+5:10
over its 20 min
07:20
Paused
<?= ws_run_clock(['seconds' => 440, 'planned' => 20]) ?> // running <?= ws_run_clock(['seconds' => 90, 'planned' => 20]) ?> // ending <?= ws_run_clock(['seconds' => -310, 'planned' => 20]) ?> // over <?= ws_run_clock(['seconds' => 440, 'planned' => 20, 'state' => 'paused']) ?>
States
| State | Behavior |
|---|---|
| Running | Counts down in --text-dark, labelled "left of 20 min". |
| Ending | The last two minutes, in --color-warning-ink. The live region says "Two minutes left" once. |
| Over | Counts up with a plus sign in --brand-ink, labelled "over its 20 min". The live region says so, then once for each further minute. |
| Paused | The value in --text-muted, labelled "Paused". Remove data-ends-at and the script stops moving it. |
Real-World Usage
The cockpit's Now card. The server sends when the block is due to end; /js/ws-run-clock.js does the rest. This one is live.
Exercise
Sailboat Retrospective
07:20
left of 20 min
<?= ws_run_clock(['seconds' => $left, 'planned' => 20, 'endsAt' => $endsAtMs]) ?> <script src="/js/ws-run-clock.js?v=2"></script>
Options
| Option | Type | Default | Purpose |
|---|---|---|---|
seconds | int | null | Seconds left on the block; negative means over. Builds the value, the label, the state and the accessible name. |
value | string | '' | The text shown when seconds is not given |
planned | int | null | The block's planned minutes, for the label |
label | string | derived | Replaces the derived label; the script then leaves it alone |
state | string | derived | running, ending, over or paused |
size | string | 'lg' | md, lg or xl |
endsAt | int | null | Epoch milliseconds the block is due to end. With it the script keeps the clock moving. |
id | string | '' | Element ID |
class | string | '' | Additional CSS classes |
attrs | array | [] | Extra HTML attributes |
Accessibility
| Concern | Behavior |
|---|---|
| Semantics | role="timer", which is aria-live="off", so a second ticking by is never read out. |
| Name | The accessible name says the time in words ("7 minutes 20 seconds left of 20 minutes") and follows the clock to the second, so 07:20 is never spelled out. A timer is never read aloud on its own, so the name can change without speaking. |
| Announcements | A polite live region inside the clock speaks on entering the last two minutes, on going over, and once for each further minute over. Never on page load. |
| Colour | State is in the text (the plus sign and the label), never colour alone. --brand-ink and --color-warning-ink pass AA on white and on paper. |
| Motion | No pulse or flash in any state. |
Tokens
| Token | Used for |
|---|---|
--text-h1 / --text-display-lg / --text-display-xl | The value at md, lg and xl |
--font-body, --font-bold, --tracking-tight | The value: Inter, bold, tight, with tabular figures |
--text-dark | Running |
--color-warning-ink | Ending |
--brand-ink | Over |
--text-muted | Paused |
--text-small, --text-default | The label |
CSS Classes
| Class | Purpose |
|---|---|
.ws-run-clock | The clock. Carries data-ws-run-clock, data-state, and data-planned / data-ends-at when given. |
.ws-run-clock--md / --lg / --xl | Size |
.ws-run-clock--running / --ending / --over / --paused | State; the script swaps it as time passes |
.ws-run-clock__value | The readout |
.ws-run-clock__label | The label beside it |
Files
| File | Purpose |
|---|---|
includes/components/helpers.php | ws_run_clock() and its formatting helpers |
includes/components/run-clock.php | Template: the clock, its label and its live region |
includes/components/components.css | Styles (.ws-run-clock rules) |
js/ws-run-clock.js | Keeps clocks with data-ends-at right from the timestamp |