# Timer

## Usage

`Timer` writes a running duration into a `<time>` element. `startTime` is unix milliseconds. Omit it and the count starts when this timer mounts. The text and `dateTime` are written on the element. The component does not re-render on every tick, and it does not use `aria-live`.

`format="elapsed"` is the default. Under a minute it reads `Ns`. Under an hour it reads `Nm NNs`. At an hour and beyond it reads `Nh NNm` and drops seconds, both in the text and in `dateTime` (`PT{minutes * 60}S`). `format="clock"` stays on seconds: `m:ss`, or `h:mm:ss` past an hour, with `dateTime="PT{seconds}S"`.

The clock updates once a second until the elapsed format reaches an hour, then once a minute. If `startTime` is still in the future, the first change waits until one second after that start.

Typography matches `Timestamp`. `type` defaults to `supporting`, `color` to `secondary`. `type="inherit"` does not wrap the time in `Text`, so it takes the surrounding font. `color="disabled"` uses the disabled text color. `size` and `weight` override the type scale the same way they do on `Text`.

```vue
<script setup lang="ts">
import { Text } from '@astryx-vue/core/Text'
import { Timer } from '@astryx-vue/core/Timer'
</script>

<template>
  <Text type="body" color="primary">
    Processing for <Timer type="inherit" color="inherit" />
  </Text>
</template>
```

### Anatomy

- **Elapsed time**: Semantic time element containing a standardized elapsed duration.

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Use `elapsed` next to a status word, and `clock` when the reader is watching seconds. |
| Do | Pass the same `startTime` when two timers must agree. |
| Do | Use `type="inherit"` inside a sentence so the duration matches the line. |
| Don't | Announce every tick. The time element updates in place and stays quiet. |
| Don't | Expect second precision from `elapsed` after one hour. That format switches to minutes on purpose. |

## Examples

### Timer — Formats

Elapsed compact units and stopwatch clock notation shown from the same start time.

```vue
<script setup lang="ts">
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
import { Timer } from '@astryx-vue/core/Timer'

const startedAt = Date.now() - 3_753_000
</script>

<template>
  <Stack direction="vertical" :gap="3">
    <Stack direction="horizontal" :gap="3" align="center">
      <Text type="supporting" color="secondary">
        Elapsed
      </Text>
      <Timer :start-time="startedAt" type="body" color="primary" />
    </Stack>
    <Stack direction="horizontal" :gap="3" align="center">
      <Text type="supporting" color="secondary">
        Clock
      </Text>
      <Timer format="clock" :start-time="startedAt" type="body" color="primary" />
    </Stack>
  </Stack>
</template>
```

### Timer — Inline

A Timer composed into status copy while inheriting the surrounding typography.

```vue
<script setup lang="ts">
import { Text } from '@astryx-vue/core/Text'
import { Timer } from '@astryx-vue/core/Timer'
</script>

<template>
  <Text type="body" color="primary">
    Processing for <Timer type="inherit" color="inherit" />
  </Text>
</template>
```

### Timer — Typography

Timer using its Timestamp-matched default typography and an emphasized override.

```vue
<script setup lang="ts">
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
import { Timer } from '@astryx-vue/core/Timer'

const startedAt = Date.now() - 128_000
</script>

<template>
  <Stack direction="vertical" :gap="3">
    <Text type="supporting" color="secondary">
      Default
    </Text>
    <Timer :start-time="startedAt" />
    <Text type="supporting" color="secondary">
      Emphasized
    </Text>
    <Timer :start-time="startedAt" type="body" size="xl" color="primary" weight="semibold" />
  </Stack>
</template>
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `startTime` | `number` | — | Unix time in milliseconds when the operation began. Omit it to start at mount. |
| `format` | `'elapsed' \| 'clock'` | `'elapsed'` | `elapsed` uses compact units and drops seconds after one hour. `clock` stays second-precise. |
| `type` | `TextType \| 'inherit'` | `'supporting'` | Semantic text type, matching Timestamp. `inherit` skips the Text wrapper. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | — | Explicit font size. Overrides the size that comes from `type`. |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'inherit' \| 'disabled'` | `'secondary'` | Text color. `disabled` uses the disabled text token. |
| `weight` | `'regular' \| 'medium' \| 'semibold' \| 'bold'` | — | Font weight override. |

## Theme

The root class is `astryx-timer`. Digits use tabular numbers. `data-color` selects `primary`, `secondary`, `accent`, or `disabled`.