# Utilities & Object Attributes

## Tag

A property label attached to an object, characterising it with contextual information.

```tsx
import { Tag } from '@theorchard/suite-components';
```

### Variants

| `variant` | Icon source | Usage |
|---|---|---|
| (none) | — | Plain text tag |
| `'flag'` | `CountryFlag` (by `iconName`) | Country / territory tags |
| `'category'` | `GlyphIcon` (by `iconName`) | Category / type tags |
| `'app'` | `AppIcon` (by `iconName`) | App / platform tags |

### Key Props

| Prop | Type | Description |
|---|---|---|
| `text` | string | Tag label text |
| `variant` | `'flag' \| 'category' \| 'app'` | Tag type (determines icon style) |
| `iconName` | string | Icon name (required for `flag`, `category`, `app` variants) |
| `indicator` | `'warning' \| 'error'` | Adds a semantic dot indicator |
| `brand` | string | Brand key for `app` variant |

### Example

```tsx
<Tag text="Rock" variant="category" iconName="music" />
<Tag text="United States" variant="flag" iconName="us" />
<Tag text="Spotify" variant="app" iconName="spotify" />
<Tag text="Draft" indicator="warning" />
```

---

## TagCloud

Expandable container of `Tag` components with overflow handling.

```tsx
import { TagCloud } from '@theorchard/suite-components';
```

Use instead of manually rendering a flex-wrapped list of `Tag` elements. Automatically handles "show more / show less" behaviour.

---

## Pill

Clickable interactive badge representing a concept or object. Clicking reveals a `Popover` with more information.

```tsx
import { Pill } from '@theorchard/suite-components';
```

### Pill vs Tag

| Pill | Tag |
|---|---|
| Interactive — opens popover on click | Non-interactive display only |
| Represents a clickable concept | Represents a property/label |

---

## PillCloud

Expandable container of `Pill` components.

```tsx
import { PillCloud } from '@theorchard/suite-components';
```

---

## Metadata

A label-value pair or atom group for displaying object attributes.

```tsx
import { Metadata } from '@theorchard/suite-components';
```

Use to display structured key-value information on detail pages. Often composed inside a `Section.Body` or `PageHeader`.

---

## MetadataList

Horizontal, divider-separated list of `Metadata` items or other molecules.

```tsx
import { MetadataList } from '@theorchard/suite-components';
```

### Example

```tsx
<MetadataList>
  <Metadata label="Label" value="Sony Music" />
  <Metadata label="Release Date" value="2024-03-15" />
  <Metadata label="Territories" value="Worldwide" />
</MetadataList>
```

---

## Divider

Visual separator between components.

```tsx
import { Divider } from '@theorchard/suite-components';
```

Use `Divider` for horizontal or vertical visual separation. Do NOT use a raw `<hr>` element.

---

## TruncatedText

Wrapper that truncates a string with an ellipsis, either dynamically (by container width) or at a fixed character width.

```tsx
import { TruncatedText } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `text` | string | The full text to potentially truncate |
| `maxWidth` | number | Fixed max width in pixels (optional) |
| `showTooltip` | boolean | Shows full text in a tooltip when truncated |

Use `TruncatedText` in table cells, cards, and anywhere text might overflow. Do NOT use CSS `overflow: hidden` with `text-overflow: ellipsis` directly — use this component for consistency and accessibility.

---

## HiddenCount

Shows a count of hidden items with an expand glyph.

```tsx
import { HiddenCount } from '@theorchard/suite-components';
```

Use at the end of a truncated list to indicate that more items exist and allow expansion.

---

## FilterCloud

Expandable container of filter controls (`Select`, `SearchInput`, `DatePicker`, etc.) with a "show more / show less" toggle.

```tsx
import { FilterCloud } from '@theorchard/suite-components';
```

### Key Props

| Prop | Type | Description |
|---|---|---|
| `defaultVisible` | number | Number of filters visible before "Show more" |
| `children` | ReactNode | Filter components |

Use `FilterCloud` in `Section.Filters` or `Page.Toolbar` when more filters than can comfortably fit need to be available.

---

## ExpandableContent

Collapsible content panel inside a container (e.g. a `Section`).

```tsx
import { ExpandableContent } from '@theorchard/suite-components';
```

Use for optional or secondary content that should be hidden by default to reduce cognitive load.

## Common Mistakes

- Do NOT use a raw `<hr>` — use `Divider`.
- Do NOT manually truncate text with CSS — use `TruncatedText`.
- Do NOT use `Pill` as a non-interactive label — use `Tag`.
- Do NOT use `Tag` as a clickable element — use `Pill`.
- Do NOT manually implement "show more" for tag lists — use `TagCloud` or `PillCloud`.