# Statistical Mapping Selector (SMS)

**Version:** 1.0.0
**Status:** Production Ready
**Category:** Form Components

## Visao Geral

O Statistical Mapping Selector (SMS) e um componente de formulario para selecao rapida de mapeamentos, inspirado no Pen&Pad Project. Apresenta opcoes ordenadas por frequencia estatistica de uso, sem exibir os percentuais explicitamente.

### Caracteristicas Principais

- **4 opcoes inline** antes do botao "..."
- **Ordenacao estatistica implicita** (opcoes mais frequentes primeiro)
- **Badge "Auto"** para mapeamentos automaticos com pre-selecao
- **Popup com busca** para alternativas adicionais
- **Navegacao por teclado** completa
- **Integracao HTMX** para carregamento dinamico

## Anatomia

```
┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│  LABEL                                               [Auto Badge]   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────┐     │
│  │ Opcao 1  │ │ Opcao 2  │ │ Opcao 3  │ │ Opcao 4  │ │ ...+N │     │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └───────┘     │
│       ▲                                                             │
│  selecionado                                                        │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘
```

### Componentes

| Componente | Classe | Descricao |
|------------|--------|-----------|
| Container | `.sms` | Wrapper principal |
| Label | `.sms-label` | Rotulo com icone opcional |
| Auto Badge | `.sms-auto-badge` | Indicador de mapeamento automatico |
| Options Container | `.sms-options` | Container flexbox das opcoes |
| Option | `.sms-option` | Botao de opcao individual |
| More Button | `.sms-more` | Botao "..." para popup |
| More Count | `.sms-more-count` | Contador de opcoes adicionais |
| Popup | `.sms-popup` | Container do popup |
| Popup Search | `.sms-popup-search` | Campo de busca no popup |
| Popup List | `.sms-popup-list` | Lista de opcoes no popup |

## Estados

### Option States

| Estado | Classe | Visual |
|--------|--------|--------|
| Default | `.sms-option` | Fundo branco, borda mint |
| Hover | `:hover` | Fundo mint 5%, borda teal |
| Selected | `.sms-option-selected` | Fundo emerald-abyss, texto mint |
| Auto-Selected | `.sms-option-auto` | Borda tracejada, indica sugestao |
| Disabled | `:disabled` | Opacidade 50%, cursor bloqueado |

### Component States

| Estado | Classe | Uso |
|--------|--------|-----|
| Auto-Mapping | `.sms-auto` | Quando tem sugestao automatica |
| Loading | `.sms-skeleton` | Skeleton animado durante load |
| Disabled | `data-disabled="true"` | Componente desabilitado |

## Variantes

### Tamanho

```html
<!-- Small - para interfaces densas -->
<div class="sms sms-sm">...</div>

<!-- Default -->
<div class="sms">...</div>

<!-- Large - para destaque -->
<div class="sms sms-lg">...</div>
```

### Layout

```html
<!-- Wrap (default) - quebra linha se necessario -->
<div class="sms sms-wrap">...</div>

<!-- No Wrap - scroll horizontal -->
<div class="sms sms-nowrap">...</div>

<!-- Grid - 4 colunas -->
<div class="sms sms-grid">...</div>
```

## Uso

### HTML Basico

```html
<div class="sms" data-field="primary_pack">
  <label class="sms-label">
    <i class="fas fa-box"></i> Embalagem Primaria
  </label>
  <div class="sms-options">
    <button class="sms-option sms-option-selected" data-value="1">Blister</button>
    <button class="sms-option" data-value="2">Frasco</button>
    <button class="sms-option" data-value="3">Ampola</button>
    <button class="sms-option" data-value="4">Bisnaga</button>
    <div class="sms-popup-container">
      <button class="sms-more">
        <i class="fas fa-ellipsis-h"></i>
        <span class="sms-more-count">+8</span>
      </button>
      <div class="sms-popup" hidden>
        <div class="sms-popup-search">
          <i class="fas fa-search"></i>
          <input type="text" placeholder="Buscar...">
        </div>
        <div class="sms-popup-list">
          <button class="sms-popup-option" data-value="5">Sache</button>
          <!-- mais opcoes -->
        </div>
      </div>
    </div>
  </div>
  <input type="hidden" name="primary_pack_id" value="1">
</div>
```

### Jinja2 Macro (PHD_CURANS)

```jinja
{% from 'partials/_sms.html' import sms %}

{{ sms(
    field='primary_pack',
    label='Embalagem Primaria',
    icon='fa-box',
    options=[
        {'value': 1, 'label': 'Blister'},
        {'value': 2, 'label': 'Frasco'},
        {'value': 3, 'label': 'Ampola'},
        {'value': 4, 'label': 'Bisnaga'},
    ],
    more_options=[
        {'value': 5, 'label': 'Sache'},
        {'value': 6, 'label': 'Flaconete'},
    ],
    selected=1,
    auto=False
) }}
```

### Com Auto-Mapping

```jinja
{{ sms(
    field='secondary_pack',
    label='Embalagem Secundaria',
    icon='fa-boxes-stacked',
    options=top_4_options,
    more_options=remaining_options,
    selected=suggested_value,
    auto=True  # Ativa badge Auto e pre-selecao
) }}
```

## Comportamentos

### Ordenacao Estatistica

As opcoes devem ser passadas ja ordenadas por frequencia descendente. As 4 primeiras aparecem inline, as demais vao para o popup.

```python
# Backend - ordenar por frequencia
options = get_mapping_options_ordered_by_frequency(field)
top_4 = options[:4]
remaining = options[4:]
```

### Eventos JavaScript

O componente dispara eventos customizados para integracao:

```javascript
// Escutar mudancas
document.addEventListener('sms:change', (e) => {
    console.log('Campo:', e.detail.field);
    console.log('Valor:', e.detail.value);
    console.log('Label:', e.detail.label);
    console.log('Auto:', e.detail.auto);
    console.log('Do Popup:', e.detail.fromPopup);
});
```

### HTMX Integration

```html
<div class="sms"
     hx-get="/api/mappings/primary_pack"
     hx-trigger="load"
     hx-swap="innerHTML">
  <div class="sms sms-skeleton">
    <!-- Skeleton enquanto carrega -->
  </div>
</div>
```

## Navegacao por Teclado

| Tecla | Acao |
|-------|------|
| `Tab` | Move foco entre opcoes |
| `Enter` / `Space` | Seleciona opcao focada |
| `Arrow Left/Right` | Move entre opcoes inline |
| `Arrow Up/Down` | Move no popup |
| `Escape` | Fecha popup |

## Tokens CSS

Variaveis CSS disponiveis para customizacao:

```css
:root {
  /* Opcao */
  --sms-option-bg: white;
  --sms-option-border: rgba(183, 228, 213, 0.4);
  --sms-option-text: var(--graphite-depth);
  --sms-option-hover-bg: rgba(183, 228, 213, 0.05);
  --sms-option-selected-bg: var(--emerald-abyss);
  --sms-option-selected-text: var(--mint-signal);

  /* Auto badge */
  --sms-auto-badge-bg: rgba(42, 161, 152, 0.15);
  --sms-auto-badge-text: var(--teal-intense);

  /* Popup */
  --sms-popup-bg: white;
  --sms-popup-shadow: 0 4px 20px rgba(11, 45, 42, 0.15);

  /* Sizing */
  --sms-option-padding-x: 1rem;
  --sms-option-padding-y: 0.5rem;
  --sms-option-min-width: 5rem;
}
```

## Arquivos Relacionados

| Arquivo | Projeto | Descricao |
|---------|---------|-----------|
| `tokens/sms.css` | Design System | Tokens e estilos CSS |
| `partials/_sms.html` | PHD_CURANS | Macro Jinja2 |
| `static/js/sms.js` | PHD_CURANS | Comportamento JavaScript |
| `showcase/components/sms-showcase.html` | Design System | Demo interativo |

## Boas Praticas

1. **Sempre ordene por frequencia** - As opcoes inline devem ser as mais usadas
2. **Limite a 4 inline** - Mais que isso polui visualmente
3. **Use Auto apenas com confianca alta** - Evite sugestoes incorretas
4. **Inclua busca no popup** - Facilita quando ha muitas opcoes
5. **Mantenha labels curtos** - 1-2 palavras idealmente

## Acessibilidade

- Botoes tem `role` implicito
- Popup usa `role="listbox"`
- Estados visuais nao dependem apenas de cor
- Focus visible em todos os elementos interativos
- Navegacao completa por teclado
