# Artifact manifest

The final output of a piece of work, listed by the app's own entity kinds. A header names the version shown and where it stands, in the app's words. Each kind is a group with its icon, its count in the kind's plural and an optional plain-words line; its heading is a button that opens the list of its items (`aria-expanded`). Each item opens through the app: an address drawn with the app's `link`, or `onOpen`. Under the groups, the total counts every item. With `versions`, every round's version is listed and the one shown is marked; a version a later one replaced says "Superseded" in words.

The counts come from the items given, never typed. Kinds take their icons and nouns from EntityKindsProvider (or a preset); an item's name and label are drawn as text, never as markup.

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

## Install

```bash
npx candor-ui@4 add artifact-manifest
```

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

## Example

```tsx
"use client"

import * as React from "react"
import { Braces, Table2, Waypoints } from "lucide-react"
import { EntityKindsProvider, type EntityKindInfo } from "@/components/candor/entity-chip"
import { ArtifactManifest, type ManifestItem, type ManifestVersion } from "@/components/candor/artifact-manifest"

// Your app's own kinds, with a plural where adding "s" isn't how the word works.
const kinds: Record<string, EntityKindInfo> = {
  automation: { Icon: Waypoints, noun: "Automation" },
  table: { Icon: Table2, noun: "Table" },
  rule: { Icon: Braces, noun: "Validation rule" },
  policy: { Icon: Braces, noun: "Access policy", plural: "Access policies" },
}

const versions: ManifestVersion[] = [
  { id: "v1.1", label: "v1.1", status: "Ready for your admin" },
  { id: "v1.0", label: "v1.0", status: "Checked in a sandbox", superseded: true },
]

const items: Record<string, ManifestItem[]> = {
  "v1.1": [
    { id: "a1", entity: { kind: "automation", name: "onboard_customer", label: "Onboard a customer" }, href: "#code/onboard_customer" },
    { id: "a2", entity: { kind: "automation", name: "renewal_reminder", label: "Renewal reminder" }, href: "#code/renewal_reminder" },
    { id: "t1", entity: { kind: "table", name: "subscriptions" }, href: "#code/subscriptions" },
    { id: "r1", entity: { kind: "rule", name: "end_after_start", label: "End date after start date" }, href: "#code/end_after_start" },
    { id: "p1", entity: { kind: "policy", name: "billing_read", label: "Billing team can read" }, href: "#code/billing_read" },
    { id: "p2", entity: { kind: "policy", name: "billing_edit", label: "Billing leads can edit" }, href: "#code/billing_edit" },
  ],
  "v1.0": [
    { id: "a1", entity: { kind: "automation", name: "onboard_customer", label: "Onboard a customer" }, href: "#code/onboard_customer" },
    { id: "t1", entity: { kind: "table", name: "subscriptions" }, href: "#code/subscriptions" },
  ],
}

export default function Example() {
  const [shown, setShown] = React.useState("v1.1")
  const version = versions.find((v) => v.id === shown) ?? versions[0]!
  return (
    <EntityKindsProvider kinds={kinds}>
      <ArtifactManifest
        className="max-w-xl"
        title="Delivery package"
        version={version}
        items={items[shown] ?? []}
        kindNotes={{
          automation: "Steps that run on their own when a record changes.",
          table: "Where the new data is kept.",
          rule: "Checks that stop a record being saved with a mistake in it.",
          policy: "Who can see and change what.",
        }}
        versions={versions}
        onVersionSelect={setShown}
      />
    </EntityKindsProvider>
  )
}
```

## <ArtifactManifest>

Props:

- `version: ManifestVersion`: The version shown: its name and where it stands, in the app's words.
- `items: ManifestItem[]`: What this version holds, grouped by `entity.kind` in the order the kinds first appear.
- `kindNotes?: Record<string, string> | undefined`: A plain-words line for a kind, by kind id: what these are, in the app's words.
- `versions?: ManifestVersion[] | undefined`: Every round's version, in the order to list them; the one whose id is `version.id` is marked as shown.
- `onVersionSelect?: ((id: string) => void) | undefined`: Makes each other version a button; called with its id, for the app to show that version.
- `onOpen?: ((id: string) => void) | undefined`: Makes an item without an `href` a button; called with its id.
- `title?: string | undefined`: The heading, in the app's words: "Delivery package". Left out, "What was produced".
- `headingLevel?: HeadingLevel | undefined`: The level of the heading. Defaults to one below the nearest `HeadingScope`, else 2.
- `className?: string | undefined`

## Strings (`artifactManifest`)

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

- `title`: What was produced
- `group`: {count} {noun}
- `total`: { one: "{count} item", other: "{count} items" }
- `empty`: Nothing in this version yet.
- `versions`: Versions
- `shown`: Shown
- `superseded`: Superseded
- `supersededNote`: A later version replaced this one.

## Types

### ManifestItem

One thing a piece of work produced, as the app names it.

```ts
{
  /** The item's id, which `onOpen` is called with. */
  id: string;
  /** What it is: its kind (one of the app's entity kinds), its identifier and an optional friendlier label. */
  entity: EntityRef;
  /** An address in the app where the item opens ("/code/flows/onboarding"), drawn through the app's link. */
  href?: string | undefined;
}
```

### ManifestVersion

One version of what was produced: one per round of work.

```ts
{
  /** The version's id, which `onVersionSelect` is called with. */
  id: string;
  /** Its name in the app's words: "v1.1". */
  label: string;
  /** Where it stands, in the app's words: "Ready for your admin". */
  status: string;
  /** A later version replaced it. Said in words beside it, and under the heading while it is shown. */
  superseded?: boolean | undefined;
}
```

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

### EntityRef

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

```ts
{
  kind: EntityKind;
  /** The identifier, e.g. "orders.status" or "billing.invoice.due_date". */
  name: string;
  /** A friendlier label when there is one, e.g. "Region". */
  label?: string | undefined;
  /** Where it lives, when more than one place is in scope, e.g. "Shop staging". */
  location?: string | undefined;
}
```

### EntityKind

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

What kind of thing an entity is: "record", "table", "workflow"… Any string; the app registers each kind's icon and noun (see EntityKindsProvider), and presets cover the kinds of the systems an app commonly works with.

```ts
string
```

## Motion

- **open** (reveal, size): The chevron beside a kind turns when the person opens its list and turns back when they close it. Under reduced motion it turns at once.

Set with `--cd-motion-artifact-manifest-<moment>-*` in your brand file; the families are in the design reference.

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