Artifact manifest
ProThe 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.
Preview
Loading the preview
Install
First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/artifact-manifest
Brings in: badge, bidi, chat, collapsible, entity-chip, heading-level, heading-scope, link, locale, motion, tokens, utils · npm: lucide-react@^1.67.0
Usage
"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>
| Prop | Type | Default | Description |
|---|---|---|---|
| versionrequired | ManifestVersion | — | The version shown: its name and where it stands, in the app's words. |
| itemsrequired | 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 | — | Extra classes for the outer element. |
Strings
The fixed words, in English by default. Change any of them under artifactManifest in <LocaleProvider strings={{ … }}>; the table is exported as artifactManifestStrings.
| Key | English |
|---|---|
| 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. |
Motion
| Moment | Family | What it does |
|---|---|---|
| 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.
Types
- ManifestItem
- One thing a piece of work produced, as the app names it.
{ /** 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.
{ /** 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 from @/lib/candor/heading-level
- 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.
1 | 2 | 3 | 4 | 5 | 6- EntityRef from @/lib/candor/chat
{ 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 from @/lib/candor/chat
- 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.
string