# Evidence gallery

An ordered grid of evidence images, such as the screenshots taken while checking the work, with how many there are under its heading. Images with the same `group` (the app's: by criterion, by step) sit together under its heading, groups in the order first seen; images with none come first, under the gallery's own heading. With `limit`, the first images are shown and "Show all N" shows the rest, focus going to the first image it shows.

One lightbox walks the whole set, in the order the gallery draws it, hidden images and every group included: an image opens it there, Previous and Next (and the arrow keys) go through the rest, and closing it puts focus on the thumbnail of the image last shown, or back on the one that opened it when that image isn't shown. Each image is an EvidenceImage: the app's own copy, never an address from model output, with the checking agent's description drawn as theirs.

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

## Install

```bash
npx candor-ui@4 add evidence-gallery
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/evidence-gallery`.
It brings in: bidi, button, evidence-image, heading-level, heading-scope, locale, tokens, utils.

## Example

```tsx
"use client"

import { EvidenceGallery } from "@/components/candor/evidence-gallery"
import type { EvidenceImageData } from "@/components/candor/evidence-image"

const checker = { id: "check", name: "Checking agent", role: "reviewer" }
const shot = (file: string) => `/examples/screenshots/${file}-light-desktop.jpg`

/*
 * The screenshots a check took, grouped by the criterion each one shows. One lightbox walks all of them, in order,
 * including the ones behind "Show all".
 */
const images: EvidenceImageData[] = [
  { id: "1", src: shot("approvals-inbox"), alt: "The approvals inbox", shows: "Three requests are waiting.", describedBy: checker, group: "Requests wait for a person" },
  { id: "2", src: shot("agent-ops-console"), alt: "The operations console", shows: "The run is paused on the request.", describedBy: checker, group: "Requests wait for a person" },
  { id: "3", src: shot("project-workspace"), alt: "The project workspace", shows: "The plan shows the approved step as done.", describedBy: checker, group: "The plan updates" },
  { id: "4", src: shot("support-copilot"), alt: "The support copilot", shows: "The reply names the agent.", describedBy: checker, group: "Replies name the agent" },
  { id: "5", src: shot("app-demo"), alt: "The demo app's thread", shows: "The agent's name is on every reply.", describedBy: checker, group: "Replies name the agent" },
]

export default function Example() {
  return <EvidenceGallery images={images} title="What the check saw" limit={3} className="max-w-2xl" />
}
```

## <EvidenceGallery>

Props:

- `images: EvidenceImageData[]`: The images, in order; an image's `group` puts it under that heading.
- `title?: string | undefined`: The heading, in the app's words. Defaults to the `title` string, "Evidence".
- `limit?: number | undefined`: How many images to show before "Show all N". Left out, every image is shown.
- `headingLevel?: HeadingLevel | undefined`: The level of the heading. Defaults to one below the nearest `HeadingScope`, else 2; group headings sit one below it.
- `className?: string | undefined`: Classes for the gallery, merged with Candor's.

## Strings (`evidenceGallery`)

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

- `title`: Evidence
- `count`: { one: "{count} image", other: "{count} images" }
- `list`: { one: "{count} image", other: "{count} images" }
- `groupList`: { one: "{group}: {count} image", other: "{group}: {count} images" }
- `showAll`: { one: "Show all {count}", other: "Show all {count}" }
- `none`: No images.

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