# Entity chip

A thing in the user's system (a record, a table, a field, a workflow…) named in a message or the composer. The kind's icon and noun are always present, so "Account" the table and "Account" the report never read alike. The identifier is the label unless a friendlier one is given; then the identifier is on hover and for screen readers.

- Registry name: `entity-chip` (`@candor/entity-chip`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/entity-chip

## Install

```bash
npx candor-ui add entity-chip
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/entity-chip`.
It brings in: chat, locale, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { EntityChip } from "@/components/entity-chip"

export default function Example() {
  return (
    <p className="max-w-lg text-sm leading-7">
      The <EntityChip entity={{ kind: "table", name: "orders", label: "Orders" }} onOpen={() => {}} /> table has a{" "}
      <EntityChip entity={{ kind: "field", name: "orders.status", label: "Status" }} onOpen={() => {}} /> field that the{" "}
      <EntityChip entity={{ kind: "workflow", name: "ship_order", label: "Ship order" }} onOpen={() => {}} /> workflow updates.
    </p>
  )
}
```

## <EntityChip>

Props:

- `entity: EntityRef`: The thing to show: its kind, identifier and optional label.
- `onOpen?: ((entity: EntityRef) => void) | undefined`: Makes the chip a button that opens the thing.
- `onRemove?: ((entity: EntityRef) => void) | undefined`: Adds a remove button, e.g. in the composer.
- `className?: string | undefined`

## <EntityKindsProvider>

The kinds of thing your app's entities can be: an icon and a noun each. Nested providers add to (and can override) the kinds above them.

Props:

- `kinds: Record<string, EntityKindInfo>`: Kind ids mapped to an icon and a noun.
- `children: React.ReactNode`

## Functions

### useEntityKinds

```ts
useEntityKinds()
```

Look up a kind's icon and noun; unknown kinds read as "Item".

## Strings (`entityChip`)

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

- `record`: Record
- `document`: Document
- `file`: File
- `table`: Table
- `field`: Field
- `person`: Person
- `link`: Link
- `code`: Code
- `workflow`: Workflow
- `report`: Report
- `dashboard`: Dashboard
- `item`: Item
- `title`: {noun}: {name}
- `titleIn`: {noun}: {name} in {location}
- `remove`: Remove {name}

## Types

### EntityKindInfo

```ts
{ Icon: LucideIcon; noun: string }
```

## 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` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.