# Share bar

Parts of one whole (coverage by source, spend by model) as a single stacked bar, with a legend that lists each part's value and share, so nothing depends on matching colours. Only the parts given with a value are drawn; one not measured (`null`, or a value that isn't a finite number) is listed as "Not measured", never drawn as zero.

With `whole`, shares are of it: parts that sum under it leave a hatched "Not accounted for" segment; parts that sum over it draw no shares at all and say they add up to more than the whole. Without `whole`, shares are of the parts' own total, and the legend says so; when a part isn't measured or is below zero, they are shares of the measured parts only, and the caption says how many were left out. Nothing is estimated to make it add up. Shares are rounded down to a tenth of a percent: only the whole reads 100%, and a part too small to reach 0.1% reads "<0.1%".

- Registry name: `share-bar` (`@candor/share-bar`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/share-bar

## Install

```bash
npx candor-ui add share-bar
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/share-bar`.
It brings in: bidi, data, locale, pattern-fill, scale, tokens, utils.

## Example

```tsx
"use client"

import { ShareBar } from "@/components/candor/share-bar"

export default function Example() {
  return (
    <div className="flex max-w-md flex-col gap-6">
      <ShareBar
        label="Spend by model, this month"
        format="currency"
        parts={[
          { id: "large", label: "Large model", value: 412 },
          { id: "small", label: "Small model", value: 96 },
          { id: "embed", label: "Embeddings", value: null },
        ]}
      />
      <ShareBar
        label="Questions answered, by source"
        whole={1200}
        parts={[
          { id: "docs", label: "Help centre", value: 640 },
          { id: "tickets", label: "Past tickets", value: 310 },
        ]}
      />
    </div>
  )
}
```

## <ShareBar>

Props:

- `label: string`: What the parts divide up, above the bar: "Spend by model".
- `parts: SharePart[]`: The parts, in order. Their labels are drawn as text, isolated, so a model's or a tool's name can't reorder the line.
- `whole?: number | undefined`: The whole the parts are of, when it's known: shares are of it, and what the parts don't cover is shown. One that isn't a finite number is treated as not given.
- `format?: ValueFormat | undefined` (default `"number"`): How values are written: number, percent (0–1), currency (USD) or duration (seconds). Defaults to number.
- `patterns?: ChartPatternMode | undefined` (default `"auto"`): When each part carries a hatch pattern as well as a colour: `auto` (the default) under the high-contrast theme and in forced colours, `always`, or `never`.
- `className?: string | undefined`: Classes for the root, merged with Candor's.

## Strings (`shareBar`)

The fixed words, English by default. Override any of them under `shareBar` in `<LocaleProvider strings={{ shareBar: { … } }}>`; the table is exported as `shareBarStrings`.

- `notMeasured`: Not measured
- `belowZero`: Below zero; not drawn
- `notAccounted`: Not accounted for
- `notAccountedValue`: Not accounted for: {value}
- `over`: The parts add up to {sum}, more than the whole ({whole}).
- `ofWhole`: Shares of {whole}.
- `ofParts`: Shares of the parts' total, {sum}.
- `ofMeasured`: { one: "Shares of the measured parts' total, {sum}; {count} part left out.", other: "Shares of the measured parts' total, {sum}; {count} parts left out.", }
- `under`: <{share}
- `allZero`: Every measured part is 0.
- `nothing`: Nothing measured yet.

## Types

### SharePart

One part of the whole: its id, its words, and its measured value; `null` where it wasn't measured. A value that isn't a finite number (`NaN`, `Infinity`) is treated as not measured.

```ts
{ id: string; label: string; value: number | null }
```

## Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

### ValueFormat

Import: `import type { ValueFormat } from "@/lib/candor/data"` (item `data`, https://candor.themethodic.com/docs/data.md)

```ts
"number" | "percent" | "currency" | "duration"
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.