Skip to content
Tier

Artifact manifest

Pro

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.

Markdown

Preview

Loading the preview

Install

With the Candor CLI

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

TSX · The example above
"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>

PropTypeDefaultDescription
versionrequiredManifestVersion—The version shown: its name and where it stands, in the app's words.
itemsrequiredManifestItem[]—What this version holds, grouped by `entity.kind` in the order the kinds first appear.
kindNotesRecord<string, string> | undefined—A plain-words line for a kind, by kind id: what these are, in the app's words.
versionsManifestVersion[] | 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.
titlestring | undefined—The heading, in the app's words: "Delivery package". Left out, "What was produced".
headingLevelHeadingLevel | undefined—The level of the heading. Defaults to one below the nearest `HeadingScope`, else 2.
classNamestring | 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.

KeyEnglish
titleWhat was produced
group{count} {noun}
total{ one: "{count} item", other: "{count} items" }
emptyNothing in this version yet.
versionsVersions
shownShown
supersededSuperseded
supersededNoteA later version replaced this one.

Motion

MomentFamilyWhat it does
openreveal, sizeThe 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