# Consequence list

What an action will do, for the body of a confirm dialog: what stops, what's kept, and what can't be undone, each under its own heading as a list, in the app's words. A line of reassurance can follow ("You can start it again from the plan.").

The "What can't be undone" block is always shown. It is in the destructive tone, with a warning icon as well as the colour, unless the app says nothing here is irreversible (an empty list), which is in the neutral tone. When the app doesn't say what can't be undone (`irreversible` left out or `null`), the block says so in words ("The app hasn't said what can't be undone."), never left out. An empty list says the app has told us nothing here is irreversible. "What stops" and "What's kept" show only when the app gives them.

Inside an AlertDialog its headings sit below the dialog's title. Put the action itself in the dialog's footer.

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

## Install

```bash
npx candor-ui@4 add consequence-list
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/consequence-list`.
It brings in: bidi, heading-level, heading-scope, locale, tokens, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { Button } from "@/components/candor/ui/button"
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/candor/ui/alert-dialog"
import { TooltipProvider } from "@/components/candor/ui/tooltip"
import { ConsequenceList } from "@/components/candor/consequence-list"

export default function Example() {
  return (
    <TooltipProvider>
      <AlertDialog>
        <AlertDialogTrigger render={<Button variant="outline">Stop the build</Button>} />
        <AlertDialogContent>
          <AlertDialogHeader>
            <AlertDialogTitle>Stop the build early?</AlertDialogTitle>
            <AlertDialogDescription>The agents finish nothing more on this project until you start it again.</AlertDialogDescription>
          </AlertDialogHeader>
          {/* Each block is a list in the app's words; "What can't be undone" is always shown. */}
          <ConsequenceList
            stops={["The 2 parts in progress stop where they are.", "No new parts start."]}
            kept={["The 6 parts already built stay in the project.", "Your notes and the plan stay as they are."]}
            irreversible={["The $4.20 spent on this build so far isn't refunded."]}
            note="You can start the build again from the plan."
          />
          <AlertDialogFooter>
            <AlertDialogCancel>Keep building</AlertDialogCancel>
            <AlertDialogAction variant="destructive">Stop the build</AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
    </TooltipProvider>
  )
}
```

## <ConsequenceList>

Props:

- `stops?: string[] | undefined`: What stops when the action is taken, one line each: "The 3 runs in progress stop where they are."
- `kept?: string[] | undefined`: What the action leaves as it is, one line each: "The drafts written so far stay in the project."
- `irreversible?: string[] | null | undefined`: What can't be undone, one line each: "Emails already sent stay sent." Left out or `null`: the block says the app hasn't said. An empty list: the block says nothing here is irreversible.
- `note?: string | undefined`: A line of reassurance after the blocks, in your words: "You can start it again from the plan."
- `className?: string | undefined`
- `headingLevel?: HeadingLevel | undefined`: The level of the blocks' headings. Defaults to one below the nearest `HeadingScope`, else 2.

## Strings (`consequenceList`)

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

- `stops`: What stops
- `kept`: What's kept
- `irreversible`: What can't be undone
- `irreversibleUnsaid`: The app hasn't said what can't be undone.
- `irreversibleNone`: The app says nothing here is irreversible.

## Types from other items

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

### HeadingLevel

Import: `import type { HeadingLevel } from "@/lib/candor/heading-level"` (item `heading-level`, https://candor.themethodic.com/docs/heading-level.md)

A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.

```ts
1 | 2 | 3 | 4 | 5 | 6
```

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