# ScoreScale (score-scale)

> A read-only score meter with endpoint labels and a controlled marker.

- Entry: component
- Category: UI
- Preview capabilities: controls
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/score-scale
- JSON: https://jbm-ui.bns.studio/catalog/score-scale.json
- Registry item: https://jbm-ui.bns.studio/r/score-scale.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/score-scale
```

Also installs @jbm/tokens (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/score-scale.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/score-scale.tsx` | `src/jbm/ui/score-scale.tsx` | `@/jbm/ui/score-scale` |

## API

### `ScoreScale` (component)

Read-only meter (role meter, not an input): a label and formatted value above a track with five evenly spaced ticks and a vermilion marker, with endpoint captions below. The marker position is (value − min) / (max − min); the caller controls value. Throws RangeError for non-finite numbers or max ≤ min.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | required | Score to display. Finite values are clamped to min…max before positioning and formatting. |
| `min` | `number` | `0` | Low end of the scale; the left endpoint caption when labels is omitted. |
| `max` | `number` | `10` | High end of the scale; must be greater than min. The right endpoint caption when labels is omitted. |
| `label` | `string` | required | Visible heading and the meter's accessible name. |
| `labels` | `[string, string]` | none | Endpoint captions [low, high] shown under the track instead of min and max. |
| `formatValue` | `(value: number) => string` | `String` | Formats the clamped value for the accent readout and aria-valuetext, e.g. (v) => `${v} / 10`. |

Also accepts React.HTMLAttributes<HTMLDivElement>.

## Stage

fluid: Width fills its container (minWidth 0); the track spans it less 12px padding per side. Height is about 95 stage pixels at one line each: heading row, 22px gap, 24px track, 10px gap, 12px mono captions. Long label, value, or endpoint captions wrap and add lines.

## Examples

### Score out of ten with named endpoints

```tsx
import { ScoreScale } from "@/jbm/ui/score-scale"

<ScoreScale label="Claridad" value={6} min={0} max={10}
  labels={["Por explorar", "Lista para compartir"]}
  formatValue={(v) => `${v} / 10`} />
// Read-only meter; clamps values to the range.
```

## QA

- Drag the score control through min, the middle, and max: the marker sits on the first, center, and last ticks and never leaves the track.
- Pass a value outside the range: the marker and readout show the clamped value.
- Check long labels and endpoint captions wrap without overlapping at narrow widths.
- Screen readers announce a meter with aria-valuetext from formatValue; it is not focusable or draggable itself.

## Docs

- [Visual primitives guide](https://jbm-ui.bns.studio/docs/visual-primitives.md)

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
