noob-components/.trellis/spec/plugs-element/formatter.md

# formatter

> Value formatting utilities for table cells, dictionary lookups, and null handling.

## Source

**File**: `plugs/element/formatter.ts`

---

## Function: getValue

Returns a display value with null/undefined/empty string handling.

### Signature

```typescript
export const getValue = (
  row: any,
  column: string,
  value: any,
  index?: number
): string
```

### Behavior

| Input | Output |
|-------|--------|
| `null`, `undefined`, `''` | `'--'` |
| `0` | `'0'` |
| Any other value | The original value |

### Usage

```typescript
import { getValue } from 'plugs/element/formatter';

// In a table column formatter
const displayValue = getValue(row, 'status', value, index);
// Returns '--' for null/empty, original value otherwise
```

---

## Function: formatter

Default row formatter using dictionary lookup by scheme and property.

### Signature

```typescript
export const formatter (row: any, column: any, value: any, index: number): any
```

### Behavior

Builds dictionary key from `row.scheme + '-' + column.property`, then calls `formatterByDist`.

```typescript
// Example
formatter(row, { property: 'status' }, 'active', 0)
// Equivalent to: formatterByDist('default-status', 'active')
```

---

## Function: formatterByDist

Looks up a value from Vuex store dictionary mapping.

### Signature

```typescript
export const formatterByDist (dictKey: string, value: any): any
```

### Behavior

1. Returns `'--'` if `dictKey` is falsy
2. Gets mapping from `state.dict[dictKey]` (Vuex store)
3. Returns mapped value if found, otherwise returns original value
4. Returns `'--'` for null/undefined values via `getValue`

### Usage

```typescript
import { formatterByDist } from 'plugs/element/formatter';

// Lookup status mapping
const displayStatus = formatterByDist('user-status', user.status);
// Returns mapped label or original value if no mapping exists
```

### Vuex Dependency

```typescript
import { useStore } from 'vuex';
const { state } = useStore();

// Expected Vuex state shape:
// {
//   dict: {
//     'user-status': { active: 'Active', inactive: 'Inactive' },
//     'order-type': { 1: 'Purchase', 2: 'Refund' }
//   }
// }
```

---

## Pattern: Table Column Formatting

Typical usage in ListTable column definitions:

```typescript
const columns = [
  {
    label: 'Status',
    property: 'status',
    formatter: (row, column, value, index) => formatter(row, column, value, index)
  },
  {
    label: 'Name',
    property: 'name',
    formatter: (row, column, value, index) => getValue(row, column, value, index)
  }
];
```

---

## Related

- `plugs/element/index.ts` exports this module
- Uses Vuex store for dictionary state
- Integrates with `noob-mengyxu` ListTable component