# Metric Bar List (`metric-bar-list`) - SignalOS widget

> List of labeled proportional bars in two densities: inline (label · bar · value breakdowns) and card (header badges + headline value over a full-width bar). Parent supplies the fill fraction and tone, so no scaling or thresholding logic lives in the component.

- **Version:** 0.1.2
- **Kind:** widget · **Category:** data-display
- **Install:** `npx shadcn@latest add @signalos/metric-bar-list`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/utils, @signalos/skeleton
- **npm dependencies:** none
- **Files installed:** `src/components/widgets/metric-bar-list/MetricBarList.tsx`, `src/components/widgets/metric-bar-list/MetricBarList.types.ts`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
import { MetricBarList } from "@/components/widgets/metric-bar-list/MetricBarList"
```

## Example

```tsx
// Example: contributing metrics (card) and a breakdown (inline).
import { MetricBarList } from "@/components/widgets/metric-bar-list/MetricBarList"
import { StatusBadge } from "@/components/widgets/status-badge/StatusBadge"

export default function Example() {
  return (
    <div className="flex max-w-md flex-col gap-6">
      <MetricBarList
        items={[
          {
            id: "s1",
            badges: <StatusBadge severity="high" appearance="chip" />,
            label: "coverage_rate",
            eyebrow: "SIG-15C5 · Jun 9, 11:56",
            fraction: 1,
            value: "5.0σ",
            valueDetail: "CRLB 0.00",
            tone: "error",
            highlighted: true,
          },
          {
            id: "s2",
            badges: <StatusBadge severity="medium" appearance="chip" />,
            label: "latency_p95",
            eyebrow: "SIG-3625 · Jun 9, 11:57",
            fraction: 0.43,
            value: "2.2σ",
            valueDetail: "CRLB 0.10",
            tone: "warning",
          },
        ]}
      />

      <MetricBarList
        layout="inline"
        items={[
          { id: "1h", label: "< 1h", fraction: 0.2, value: 1, tone: "error" },
          { id: "4h", label: "< 4h", fraction: 0.4, value: 2, tone: "warning" },
          { id: "24h", label: "< 24h", fraction: 0, value: 0, tone: "muted" },
        ]}
      />
    </div>
  )
}
```

## Props

### `MetricBarLayout`

```ts
export type MetricBarLayout = "inline" | "card"
```

### `MetricBarTone`

```ts
export type MetricBarTone =
  "primary" | "success" | "warning" | "error" | "muted"
```

### `MetricBarItem`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | yes | - | Stable React key. |
| `label` | `ReactNode` | no | - | Row label (inline layout) — short mono caption. |
| `fraction` | `number` | yes | - | Fill fraction from 0 to 1. |
| `value` | `ReactNode` | yes | - | Headline value shown at the row's trailing edge. |
| `valueDetail` | `ReactNode` | no | - | Secondary value under the headline (card layout). |
| `tone` | `MetricBarTone \| undefined` | no | `"primary"` | Bar/value tone. |
| `badges` | `ReactNode` | no | - | Header badges/chips (card layout only). |
| `eyebrow` | `ReactNode` | no | - | Eyebrow / sub-caption text under the badges (card layout only). |
| `highlighted` | `boolean \| undefined` | no | - | Highlights the row (e.g. the max value) with an accent border. |
| `disabled` | `boolean \| undefined` | no | - | Disables the interactive affordance for this row. |
| `onSelect` | `(() => void) \| undefined` | no | - | Makes the row a button. |

### `MetricBarListProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly MetricBarItem[]` | yes | - |  |
| `layout` | `MetricBarLayout \| undefined` | no | `"card"` |  |
| `className` | `string \| undefined` | no | - |  |
| `data-testid` | `string \| undefined` | no | - |  |

## Changelog

# metric-bar-list
## 0.1.2
- Resolved a merge conflict.
## 0.1.1

- Add the missing `"use client"` directive - rows render `<button onClick>`,
  which crashes in a server-component tree without it.
## 0.1.0

- Initial release, genericized from the `attention-routing-01` block's
  `SignalsList` bars, deadline bars, and role bars. The domain signal/deadline
  shapes are replaced by generic `MetricBarItem`s (`fraction`, `value`, `tone`,
  `badges`, `highlighted`), with `inline` and `card` layouts and a matching
  `MetricBarListSkeleton`.