<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->

# `lr-entity-chip`

- **Import** `import '@aceshooting/lyra-ui/components/lr-entity-chip.js';` (stable tag alias; registers the tag)
- **Class** `LyraEntityChip`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/entity-chip/entity-chip.class.js`
- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
- **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
- **Deprecations** none
- **Optional peers** none
- **Themeable via** 3 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`

---

## `lr-entity-chip`

An inline `@entity` mention for agent prose: flow content, keyboard-focusable, with a hover/focus
preview popover. The knowledge-graph sibling of `lr-citation-badge`, reusing its interaction
contract wholesale. Carries ids through events only — no entity data resolution, no navigation.

Removing `text` or `type` leaves the property readback as `null` and treats it as absent when
deriving the button name. Explicit empty strings stay empty, and later valid values restore the
corresponding label/type text.

**Properties:**

- `entityId: string = ''` (attribute `entity-id`)
- `text: string = ''` — the chip's visible text
- `type: string = ''` (reflected) — lets a host theme per type from CSS, e.g.
  `lr-entity-chip[type='person'] { --lr-entity-chip-color: ... }`
- `typeLabel?: string` (attribute `type-label`) — optional spoken/visible type qualifier

The internal button always derives its own localized accessible name from `text` and optional
`typeLabel`/`type`. Blank or whitespace-only `text` uses the localized “Untitled entity” fallback
before the type template is composed, so it never produces a leading punctuation fragment such as
`, person`. An authored host `aria-label` intentionally names only the custom-element boundary;
it is not copied onto the shadow button because host naming does not cross that boundary.

**Events:** `lr-entity-select` (`detail: { entityId }`, click, or Enter while focused),
`lr-entity-open` (`detail: { entityId }`, dblclick, or Space while focused).

**Slots:** default — rich preview content (typically a compact `lr-entity-card`), shown in a
floating popover on hover/focus. No content means no popover and no hover affordance at all.

**CSS parts:** `base` (the clickable `<button>`), `label`, `popover`.

**Themeable custom properties:** `--lr-entity-chip-color` (default `var(--lr-color-brand)`,
text/accent color), `--lr-entity-chip-bg` (default `var(--lr-color-brand-quiet)`),
`--lr-entity-chip-border` (default `transparent`, the chip's `--lr-border-width-thin` outline).

The anchored detail popover is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
`--lr-overlay-surface` (default `var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default
`var(--lr-color-border)`) and `--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is
declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.

`--lr-positioning-strategy` (16.0.0) — the preview popover reads this same cascading
`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
property on `<lr-entity-chip>`; set the custom property on `:root`, a theme, or one clipping
ancestor to change every unset entity chip beneath it.

**Optional peer deps:** none.

```html
<p>
  …first described by
  <lr-entity-chip entity-id="e1" text="Ada Lovelace" type="person">
    <lr-entity-card show-focus-button="false"></lr-entity-card> </lr-entity-chip
  >.
</p>
```

**Known gotchas:**

- Reuses `lr-citation-badge`'s exact "real preview content" detection (an assigned element with no
  other `slot`, or non-whitespace text) to decide whether a popover exists at all.
- Preview content is supplementary and inert. Disable interactive actions on a slotted
  `lr-entity-card` as shown above, and handle the chip's own `lr-entity-select`/`lr-entity-open`
  events for navigation.
- A blank `entityId` disables the chip and cannot produce an activation/open event.

---