# rn-value-renderers
URL: /docs/native/docyrus/value-renderers

Read-only display components for Docyrus field values — tenant-aware dates / numbers, status companions, approval history, relation expand and more.

## Overview

Value renderers are read-only components that format a field value by type (web `DynamicValue` / `VALUE_RENDERER_MAP` parity). Every renderer accepts `DocyValueProps`; `DocyValueDynamic` picks the renderer from `field.type` (unmapped types fall back to text).

- Dates, date-times, date ranges and status follow-up dates use the tenant format from `useDateFormat()` (`DocyrusTenantProvider`), falling back to the device locale — never raw ISO strings.
- Numbers, percents and money use `useNumberFormat()`, falling back to `Intl.NumberFormat`.
- Select-style values accept an id **or** an expanded `{ id, name }` object.
- Enum options with both `icon` and `color` render as a solid chip with WCAG-contrast text.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-value-renderers
```

## Usage

```tsx
import { DocyValueDynamic } from '@/components/docyrus-native/value-renderers';

<DocyValueDynamic
  field={{ id: 'account', slug: 'account', name: 'Account', type: 'field-relation' }}
  value={{ id: 'acc-1', name: 'Acme' }}
  onExpand={item => router.push(`/accounts/${item.id}`)} />
```

## API Reference

### DocyValueProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `field` | `IField` | — | Field definition (required) |
| `value` | `unknown` | — | Value to display (required) |
| `record` | `Record<string, unknown>` | — | Full record — companion columns (`__<slug>_currency`, `__<slug>_country`, `__<slug>_secondary`, `__<slug>_description`, `__<slug>_followup_date`) |
| `enumOptions` | `EnumOption[]` | — | Options for select-based fields |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size scale (native) |
| `uuid` | `boolean` | `false` | Identity: compact `#` chip; press reveals, long-press calls `onCopy` |
| `onCopy` | `(text: string) => void` | — | Identity copy handler (wire `expo-clipboard`) |
| `onExpand` | `(item: { id; name? }) => void` | — | Relation expand button |
| `renderExpandContent` | `(item: { id; name? }) => ReactNode` | — | Relation expand content (bottom sheet) |
| `expandIcon` | `ReactNode` | — | Custom expand glyph |
| `onComposeEmail` | `(email: string) => void` | — | Email: open the app composer instead of `mailto:` |
| `onSendMessage` | `(phone: string) => void` | — | Phone: send-message button |
| `client` | `RestApiClient` | — | Email: compose button opening [rn-email-compose-dialog](/docs/native/docyrus/email-compose-dialog). Phone: message button opening [rn-instant-message-compose-dialog](/docs/native/docyrus/instant-message-compose-dialog). `onComposeEmail` / `onSendMessage` win when set |
| `className` | `string` | — | Container class |
| `textClassName` | `string` | — | Text class (native) |

### Field type → renderer (`VALUE_RENDERER_MAP`)

| Types | Renderer |
|---|---|
| `field-text`, `-textarea`, `-display`, `-code` | `DocyValueText` |
| `field-password` | `DocyValuePassword` (masked + eye toggle) |
| `field-number` / `-percent` / `-money` / `-duration` / `-rating` | Number / Percent / Money / Duration / Rating (`field.maxRating`) |
| `field-checkbox` / `-switch` | Checkbox / Switch |
| `field-email` / `-phone` / `-url` | Email / Phone / Url |
| `field-color` / `-icon` / `-currency` | Color / Icon / CurrencyCode |
| `field-select`, `-enum`, `-systemEnum` | `DocyValueSelect` |
| `field-multiSelect`, `-tagSelect` | `DocyValueMultiSelect` |
| `field-radioGroup` / `-status` / `-approvalStatus` / `-list` | RadioGroup / Status / ApprovalStatus / List |
| `field-userSelect` / `-userMultiSelect` / `-relation` | User / UserMulti / Relation |
| `field-date` / `-dateTime` / `-time` / `-dateRange` | Date / Datetime / Time / DateRange |
| `field-file` / `-image` / `-avatar` | File / Image / Avatar |
| `field-htmlEditor`, `-emailEditor` | `DocyValueRichText` |
| `field-markdown` | `DocyValueMarkdown` |
| `field-codeEditor`, `-jsonata`, `-handlebars` | `DocyValueCode` |
| `field-docEditor` | `DocyValueDocEditor` (Plate JSON → preview text) |
| `field-json`, `-jsonSchema`, `-queryBuilder`, `-inlineForm` | `DocyValueJson` |
| `field-adaptiveCard` | `DocyValueAdaptiveCard` (summary) |
| `field-inlineData`, `-schemaRepeater`, `-systemBuffer`, `-systemVector`, `-systemTextArray`, `-systemUuidArray` | `DocyValueInlineData` |
| `field-taskList` / `-todo` / `-locationSelect` | TaskList / Todo / Location |
| `field-conversationChannel` / `-fileStorageFolder` | ConversationChannel / FileStorageFolder |
| `field-button` / `-formula` / `-relatedField` | Button / Formula / RelatedField |
| `field-identity`, `-autonumber` | `DocyValueIdentity` |

## Notable renderers

### DocyValueStatus

Solid primary badge, the sub-status (`__<slug>_secondary`), notes (`__<slug>_description`) and follow-up date (`__<slug>_followup_date`, tenant date format).

### DocyValueApprovalStatus

Status badge, last-response summary (actor avatar, time, comments) and response history. Bare status strings and the legacy array-of-steps shape are supported.

### DocyValueRelation

Resolves an expanded `{ id, name }` object or an id via `enumOptions`; `onExpand` / `renderExpandContent` add a trailing expand button (content opens in a bottom sheet).

### DocyValueIdentity

`#` + id; `uuid` mode shows a compact chip that reveals the id on press. `onCopy` is called on long-press.

### DocyValueImage / DocyValueFile

Accept `StoredFileValue`, URL strings and arrays. Images render a gallery strip (4 + `+N`) for arrays; files show the basename of `file_name` and the size.

### DocyValueDocEditor

Parses the persisted Plate JSON into a single preview line (80 chars); plain text / HTML still accepted.

### DocyValueMarkdown / DocyValueAdaptiveCard / DocyValuePassword

Markdown via the shared renderer; adaptive cards as `3 elements · 1 action`; passwords masked by default.

## Utilities

| Export | Description |
|---|---|
| `extractEnumId(value)` / `extractEnumLabel(value)` | Id / label from a primitive or expanded object |
| `useValueDateFormatter(kind)` | Tenant-aware `date` / `datetime` / `time` formatter |
| `useValueNumberFormatter(fallback?)` | Tenant-aware number formatter |
| `parseValueDate(value)` | Date parser (date-only strings are local days) |
| `docEditorPreviewText(value)` | Plate JSON → preview text |
| `getEnumBadgeColors`, `getEnumColorValue`, `shouldRenderEnumOptionChip` | Enum color helpers |
| `formatDuration`, `formatMoney`, `formatDateRange`, `formatTime`, `formatPhoneDisplay`, `getCompanionValue`, `getCompanionFieldSlug`, `getCurrencySymbol`, `parseDateRange`, `COMMON_CURRENCIES` | Formatting helpers |
| `DocyValueEmpty`, `getValueSizeConfig` | Empty placeholder + size scale |
| `VALUE_RENDERER_MAP` | Type → renderer registry |

## Components

| Component | Description |
|-----------|-------------|
| `DocyValueDynamic` | Dispatches on `field.type` |
| `DocyValueText`, `DocyValuePassword`, `DocyValueNumber`, `DocyValuePercent`, `DocyValueMoney`, `DocyValueDuration`, `DocyValueRating` | Text & numbers |
| `DocyValueCheckbox`, `DocyValueSwitch` | Booleans |
| `DocyValueEmail`, `DocyValuePhone`, `DocyValueUrl`, `DocyValueColor`, `DocyValueIcon`, `DocyValueCurrencyCode` | Contact & appearance |
| `DocyValueSelect`, `DocyValueMultiSelect`, `DocyValueStatus`, `DocyValueRadioGroup`, `DocyValueUser`, `DocyValueUserMulti`, `DocyValueRelation`, `DocyValueApprovalStatus`, `DocyValueList`, `DocyValueConversationChannel`, `DocyValueFileStorageFolder`, `DocyValueRelatedField`, `DocyValueIdentity` | Selection |
| `DocyValueDate`, `DocyValueDatetime`, `DocyValueTime`, `DocyValueDateRange` | Dates |
| `DocyValueFile`, `DocyValueImage`, `DocyValueAvatar` | Files |
| `DocyValueCode`, `DocyValueJson`, `DocyValueRichText`, `DocyValueDocEditor`, `DocyValueMarkdown`, `DocyValueAdaptiveCard`, `DocyValueTaskList`, `DocyValueTodo`, `DocyValueInlineData`, `DocyValueButton`, `DocyValueFormula`, `DocyValueLocation` | Complex |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyValueProps` | Renderer props |
| `DocyValueRelationItem` | `{ id; name? }` handed to expand callbacks |
| `IField`, `IFieldType`, `EnumOption` | Field contract |
| `ValueDateKind` | `'date' \| 'datetime' \| 'time'` |

## Breaking changes (web-parity release)

- Dates render in the tenant / locale format; `DocyValueNumber` / `Percent` / `Money` use the tenant number format when a provider is mounted.
- `field-autonumber` renders with `DocyValueIdentity`; `field-code` with `DocyValueText` (web parity).
- `DocyValueApprovalStatus` shows uppercase workflow statuses plus summary / history.
- Emoji glyphs replaced by `DocyrusIcon` icons.