# Screens Type Mapping & Business Rules

This document defines how entity attributes map to UI component field types and specifies the business rules for handling computed attributes, readonly fields, lookups, and workflow detection.

## Column/Field Type Mapping

Map entity attribute types to SmartTable columns and SmartForm fields:

| Entity type | SmartTable type | SmartForm type |
|-------------|----------------|----------------|
| `string` | `text` | `text` |
| `int`, `decimal` | `number` | `number` |
| `date` | `date` | `datepicker` |
| `datetime` | `datetime` | `datetimepicker` |
| `bool` | `boolean` | `checkbox` |
| `enum` | `badge` | `select` |
| `guid` (FK) | `lookup` | `lookup` |
| `text` (long) | `text` (truncated) | `textarea` |

## Computed Attribute Rule

If `entities.json` marks an attribute with `computed: true`:

- **SmartForm detail/edit:** the field MUST have `readonly: true`
- **SmartForm create:** the field MUST be ABSENT (not yet calculable)
- **SmartTable:** the field can appear normally (read-only by nature)

Example:
```json
{
  "field": "totalCompensation",
  "label": "Salaire Total",
  "type": "number",
  "readonly": true
}
```

## Readonly Field Rule

- `readonly` MUST be a boolean (`true` or `false`)
- Do NOT use string values like `"onCreate"` or `"onEdit"`
- For conditional readonly logic (e.g., readonly on create but editable on edit), use a business rule (BR-WF category) to express the condition
- The form always shows `readonly: true` or omits the field entirely

Valid:
```json
{ "field": "status", "readonly": false }
```

Invalid:
```json
{ "field": "status", "readonly": "onCreate" }
```

## SmartForm Section Location Rule

- **SmartForm in `list` section:** inline create / quick-create drawer (user creates without leaving the list)
- **SmartForm in `detail` section:** full edit page (user navigates to a dedicated form page)

Both patterns are valid. Use `list` section for high-frequency data entry (e.g., time entries). Use `detail` section for complex entities with multiple tabs.

## Lookup Field Rule

Lookup fields require explicit entity references for downstream consumers to resolve the foreign key target.

**SmartForm requirement:**
> Every SmartForm field with `type: "lookup"` MUST include `"entity": "{TargetEntityName}"`

Example:
```json
{
  "field": "department",
  "label": "Departement",
  "type": "lookup",
  "entity": "Department",
  "required": true
}
```

**SmartFilter requirement:**
> Every SmartFilter filter with `type: "lookup"` MUST include `"entity": "{TargetEntityName}"`

Example:
```json
{
  "field": "departmentId",
  "type": "lookup",
  "label": "Departement",
  "entity": "Department"
}
```

## SmartKanban Auto-Detection Rule (OBLIGATOIRE)

For each entity with an `enum` attribute named `status` having >= 3 options:

- **ADD** a SmartKanban resource in a dedicated `kanban` section (or alongside SmartTable in `list`)
- **MAP** each enum option to a Kanban column with appropriate color:
  - `gray` = draft/pending
  - `blue` = submitted/in progress
  - `green` = approved/completed
  - `red` = rejected/cancelled
  - `orange` = warning/under review
- **SET** `cardFields` to the 3-4 most relevant display attributes (typically: code, name/label, assignee, date)
- **SKIP** for:
  - Portal modules (read-only, no workflow)
  - Config/lookup entities (static, no workflow)

Example detection:
```javascript
const statusAttr = entity.attributes.find(
  a => a.name === 'status' && a.type === 'enum'
);

if (statusAttr && (statusAttr.options || []).length >= 3 && !isPortalModule) {
  // ADD SmartKanban resource
}
```

This ensures workflow entities get a visual board view — the standard UX for approval/lifecycle processes.

## SmartFilter Mandatory Rule

Every `list` section with a SmartTable MUST also have a SmartFilter resource placed BEFORE the SmartTable.

**Pattern:**
```
Section: list
  Resource 1: SmartFilter (filters come first)
  Resource 2: SmartTable (grid follows)
```

Do NOT embed `filters[]` inside SmartTable — use a dedicated SmartFilter resource instead.

**Exceptions (SKIP SmartFilter for):**
- Portal modules with a single read-only grid

This ensures consistent filtering UX across all data lists.
