# Amount button

A button that approves spending an amount, and names it: "Raise the cap to $8.00". The amount is drawn by `Money` (tabular digits, in an isolate, never animated) inside the app's words, and it is part of the button's name, so nobody approves money without hearing how much.

When the amount changes, the button is locked for `changeGuard` milliseconds (half a second unless set), with the new amount as the reason, so a press meant for the old figure can't land on the new one; the new amount is announced if the button has focus. The guard is a safety lock, not motion, and reduced motion doesn't shorten it. `onConfirm` gets the amount the person saw, so your server can refuse a stale one.

`locked` says why it can't be pressed yet (what it approves isn't complete): the button stays focusable, is marked `aria-disabled`, and is described by the reason, as `Locked` does. It is the primary button by default: one act of consent, not a choice between answers.

- Registry name: `amount-button` (`@candor/amount-button`)
- 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/amount-button

## Install

```bash
npx candor-ui@4 add amount-button
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/amount-button`.
It brings in: bidi, button, locale, locked, money, ops, tokens, use-announcer, utils.

## Example

```tsx
"use client"

import * as React from "react"
import { AmountButton } from "@/components/candor/amount-button"
import { Button } from "@/components/candor/ui/button"
import { Money } from "@/components/candor/money"

export default function Example() {
  const [cap, setCap] = React.useState(8)
  const [approved, setApproved] = React.useState<number | null>(null)
  return (
    <div className="flex max-w-md flex-col items-start gap-3">
      <div className="flex flex-wrap items-center gap-2">
        <AmountButton amount={cap} decimals="always" label="Raise the cap to {amount}" onConfirm={setApproved} />
        <Button variant="outline" onClick={() => setCap((c) => c + 2)}>
          Ask for more
        </Button>
      </div>
      <AmountButton amount={25} decimals="always" label="Agree and start · up to {amount}" locked="Answer the two open questions first." onConfirm={() => {}} />
      <p className="text-sm text-muted-foreground" aria-live="polite">
        {approved === null ? "Nothing approved yet." : <>Approved up to <Money amount={approved} decimals="always" />.</>}
      </p>
    </div>
  )
}
```

## <AmountButton>

Props:

- `amount: number`: The amount it approves, in `currency`.
- `currency?: string | undefined` (default `"USD"`): The ISO 4217 code the amount is in, e.g. `"EUR"`. Defaults to `"USD"`; the symbol and its place come from the locale.
- `decimals?: "auto" | "always" | undefined` (default `"auto"`): `"auto"` (the default): a whole amount without decimals ("$20"). `"always"`: the currency's usual decimals ("$20.00").
- `estimated?: boolean | undefined` (default `false`): The amount is an estimate: Money marks it "est." and the button's name says "estimated".
- `label?: string | undefined`: The button's words, with `{amount}` where the amount goes: "Raise the cap to {amount}", "Agree and start · up to {amount}". Defaults to the `amountButton.label` string, "Approve {amount}". Words without `{amount}` get it after them.
- `onConfirm: (amount: number) => void`: Called on a press with the amount the person saw, so the app can check it is still the amount it means.
- `locked?: string | null | undefined`: Why the button can't be pressed yet, e.g. what it approves isn't complete. `null` or left out: it can be.
- `changeGuard?: number | undefined` (default `amountButtonChangeGuard`): How long, in milliseconds, the button stays locked after the amount changes. Defaults to 500 (`amountButtonChangeGuard`); 0 turns the guard off. Not shortened under reduced motion: it guards consent, it isn't an animation.
- `variant?: "default" | "destructive" | "outline" | "secondary" | undefined` (default `"default"`): The button's look. Defaults to the primary button; `destructive` for an amount that can't be got back.
- `size?: "default" | "sm" | "lg" | undefined` (default `"default"`): The button's size. Defaults to the kit's default.
- `className?: string | undefined`: Classes for the button, merged with Candor's.

## Values

### amountButtonChangeGuard

How long, in milliseconds, AmountButton stays locked after its amount changes, unless `changeGuard` says: the same half second as DecisionBar's `decisionBarChangeGuard`.

```ts
const amountButtonChangeGuard: 500
```

## Strings (`amountButton`)

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

- `label`: Approve {amount}
- `withAmount`: {label} · {amount}
- `changed`: The amount just changed to {amount}. Check it before you go on.

## Terms used here

- **Calm level**: What Candor's motion does for a person whose operating system asks for reduced motion: the highest-precedence setting, above the app's own motion level (`none`, `calm`, `subtle` or `expressive`) and the brand file. A theme tunes how a change looks, never when it happens, so nothing depends on seeing the motion. (https://candor.themethodic.com/glossary.md#calm-level)

## 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`.
