@horizon-apps/domain-schema-core/docs/domain-data-transformers.md

Core domain schema utilities for Horizon Platform - Schema generators, data enrichers, converters and specifications

# 🔄 Domain Data Transformers

Funções para transformar estruturas de dados de domínio.

## 📋 Funcionalidades

### expandArrayFieldToBoolean
Expande um campo array em múltiplos campos booleanos independentes.

```typescript
import { expandArrayFieldToBoolean } from '@horizon-apps/domain-schema-core'

// Expandir array simples
const amenities = ['Piscina', 'Ginásio', 'Estacionamento']
const booleanFields = expandArrayFieldToBoolean(amenities)
// Resultado: [
//   { key: 'Piscina', value: true, type: 'Boolean', label: 'Piscina' },
//   { key: 'Ginásio', value: true, type: 'Boolean', label: 'Ginásio' },
//   { key: 'Estacionamento', value: true, type: 'Boolean', label: 'Estacionamento' }
// ]

// Expandir campo com value array
const field = { 
  key: 'caracteristicas', 
  value: ['Wi-Fi', 'Ar-condicionado', 'TV'] 
}
const booleanFields = expandArrayFieldToBoolean(field)
// Resultado: [
//   { key: 'Wi-Fi', value: true, type: 'Boolean', label: 'Wi-Fi' },
//   { key: 'Ar-condicionado', value: true, type: 'Boolean', label: 'Ar-condicionado' },
//   { key: 'TV', value: true, type: 'Boolean', label: 'TV' }
// ]
```

## 🎯 Casos de Uso

### Transformar características em filtros
```typescript
// Propriedade com características
const property = {
  amenities: { 
    key: 'amenities', 
    value: ['Piscina', 'Academia', 'Salão de Festas'] 
  }
}

// Expandir para campos booleanos para interface de filtros
const filterFields = expandArrayFieldToBoolean(property.amenities)
// Cada característica vira um checkbox independente na UI
```

### Converter arrays em campos individuais
```typescript
// Lista de comodidades
const comodidades = ['Elevador', 'Portaria 24h', 'Área Gourmet']

// Transformar em campos booleanos
const camposBooleanos = expandArrayFieldToBoolean(comodidades)

// Usar em formulários ou interfaces que precisam de campos individuais
camposBooleanos.forEach(campo => {
  // Cada item vira um campo separado: campo.key, campo.value, campo.label
  console.log(`${campo.label}: ${campo.value}`) // "Elevador: true"
})
```

## 🔧 API Reference

### expandArrayFieldToBoolean(field)

**Parâmetros:**
- `field`: `Field | string[]` - Campo com value array ou array de strings direto

**Retorna:** `Field[]` - Array de campos booleanos

**Comportamento:**
- Cada item do array se torna um campo com `value: true`
- A `key` e `label` são definidas com o valor do item
- O `type` é sempre definido como `'Boolean'`
- Se receber array vazio ou campo inválido, retorna array vazio

## 📝 Tipos

```typescript
interface Field {
  key: string;
  value?: any;
  label?: string;
  type?: string;
  [key: string]: any;
}
```

### sortFields
Ordena array de objetos baseado em múltiplos campos e direções.

```typescript
import { sortFields } from '@horizon-apps/domain-schema-core'

// Ordenar por nome crescente, depois preço decrescente
const properties = [
  { name: "Casa A", price: 300000, area: 120 },
  { name: "Casa B", price: 250000, area: 100 },
  { name: "Casa A", price: 280000, area: 110 }
]

const sorted = sortFields(properties, ["name:asc", "price:desc"])
// Resultado: Casa A (300k), Casa A (280k), Casa B (250k)
```

## 🔧 API Reference

### sortFields(fields, sortKeys)

**Parâmetros:**
- `fields`: `any[]` - Array de objetos para ordenar
- `sortKeys`: `string[]` - Array de regras no formato "campo:direção" (ex: `["name:asc", "price:desc"]`)

**Retorna:** `any[]` - Nova instância do array ordenado (não modifica o original)

**Direções válidas:**
- `"asc"` - Crescente (A→Z, 0→9)
- `"desc"` - Decrescente (Z→A, 9→0)

**Comportamento:**
- Ordena por múltiplos campos em sequência
- Não modifica o array original
- Ignora campos `undefined`
- Avisa sobre direções inválidas

## 🌟 Características

- ✅ **Flexível** - Aceita tanto arrays simples quanto campos complexos
- ✅ **Seguro** - Trata casos de entrada inválida
- ✅ **Tipado** - TypeScript com tipos bem definidos
- ✅ **Acentuação** - Preserva caracteres especiais e acentuação
- ✅ **Consistente** - Sempre retorna campos com mesma estrutura
- ✅ **Multi-sort** - Ordena por múltiplos campos em sequência
- ✅ **Imutável** - Não modifica arrays originais