# progress

One figure as a bar toward a limit, such as the yearly cap used or how much of an agent's budget is gone.

`label` names the figure; `source` and `figure` compute it as a kpis tile does (`count`, `sum`, `avg` or `value`
of a `column`); `max` is the figure of a full bar, a number above 0. `format` writes the figure and the limit
(`usd`: $37,900 of $140,000). The bar never passes full; the figure still shows what it is.

Category: data. Tier 1. Contract version 1.

## When to use

- A figure against a cap or budget, such as the yearly cap used.
- How close a run came to a target, such as tickets a test closed the way a person did.
- A count toward a goal for today.

## When to use another block

- Several figures with no limit. Use [`kpis`](/catalog/kpis.md).
- The figure's history. Use [`chart`](/catalog/chart.md).
- A warning once the limit is near; say it in words. Use [`callout`](/catalog/callout.md).

## Props

- `id` (name: a-z, 0-9 and -): The block's id: its Markdown anchor and its actions' route (`/act/<id>/<action>`). Default `<type>-<n>`, n counting blocks of this type depth-first from 1.
- `label` (text ≤ 60, required): The bar's label.
- `source` (a source of the screen, required): The source the figure reads.
- `figure` (one of count, sum, avg, value, default `count`): count: the rows; sum and avg: `column` over the rows; value and text: the first row's `column`.
- `column` (column): The column the figure reads; required unless figure is count.
- `max` (number, required): The figure of a full bar (above 0).
- `format` (one of number, usd, percent, duration, bytes, default `number`): How the figure and the maximum are written.

## Data

Reads `source`: its row count, or a column's sum or average, or the first row's cell.

Shape: any rows; a sum, avg or value column holds numbers.

## Actions

None: this block only shows.

## States

- **ready**: the source's rows, drawn
- **empty**: the source has no rows: an Empty part saying why and what comes next
- **error**: the source failed: "We couldn't load …" naming the block's rows, the source's sentence and Try again; the page still answers 200

## Examples

### Yearly cap used

```yaml
progress: { label: Yearly cap used, source: month, figure: value, column: cap_used_usd, max: 140000, format: usd }
```

As an agent reads it:

```markdown
<a id="progress-1"></a>

Yearly cap used: $37,900 of $140,000 (27%)

```

### A test run's match

```yaml
progress: { label: Last test run closed the same way a person did, source: last_test, figure: value, column: matched, max: 100, format: percent }
```

As an agent reads it:

```markdown
<a id="progress-1"></a>

Last test run closed the same way a person did: 83% of 100% (83%)

```

### Tickets closed today

```yaml
progress:
  label: Closed today of 250 expected
  source: closed_today
  max: 250
```

As an agent reads it:

```markdown
<a id="progress-1"></a>

Closed today of 250 expected: 3 of 250 (1%)

```

## Invalid

```yaml
progress: { label: Yearly cap used, source: month, figure: value, column: cap_used_usd, max: 0 }
```

Answers: `progress.max: write a number above 0`

## Composition

- Sits in: screen, card, columns
- Pairs with: kpis, card, callout
- One or two bars on a screen; a column of bars is a chart.
- Apple HIG: Show progress so people know where they stand, with a label that says toward what.

## Telemetry

progress.view

JSON Schema: [/catalog/progress.schema.json](/catalog/progress.schema.json)