# SmartComponent JSON Templates Reference

This document contains the canonical JSON schema examples for all SmartComponent types used in screens definition. These templates show the exact structure and required fields for each component.

## SmartTable Template

A data grid component for displaying and managing entity collections with sorting, filtering, and row-level actions.

```json
{
  "code": "{entity-plural}-grid",
  "type": "SmartTable",
  "entity": "{EntityName}",
  "label": "Grille des {entity-plural}",
  "columns": [
    { "field": "code", "label": "Code", "type": "text", "sortable": true, "width": "100px" },
    { "field": "fullName", "label": "Nom", "type": "text", "sortable": true },
    { "field": "department.name", "label": "Departement", "type": "lookup", "filterable": true },
    { "field": "status", "label": "Statut", "type": "badge", "filterable": true, "options": ["Active", "Inactive"] }
  ],
  "actions": ["create", "edit", "delete", "export"],
  "permission": "{AppCode}.{ModuleCode}.Read",
  "rowActions": [
    { "action": "edit", "permission": "{AppCode}.{ModuleCode}.Update" },
    { "action": "view-detail", "permission": "{AppCode}.{ModuleCode}.Read" }
  ],
  "defaultSort": { "field": "code", "direction": "asc" },
  "pageSize": 25
}
```

## SmartForm Template

A form component for creating and editing entity records with support for multiple tabs, field validation, and nested subtables.

```json
{
  "code": "{entity}-form",
  "type": "SmartForm",
  "entity": "{EntityName}",
  "label": "Fiche {entity}",
  "tabs": [
    {
      "label": "Informations",
      "fields": [
        { "field": "firstName", "label": "Prenom", "type": "text", "required": true, "col": 6 },
        { "field": "lastName", "label": "Nom", "type": "text", "required": true, "col": 6 },
        { "field": "email", "label": "Email", "type": "email", "required": true, "validation": "unique" },
        { "field": "department", "label": "Departement", "type": "lookup", "entity": "Department", "required": true },
        { "field": "status", "label": "Statut", "type": "select", "options": ["Active", "Inactive"], "readonly": false }
      ]
    },
    {
      "label": "Contrats",
      "type": "subtable",
      "entity": "Contract",
      "columns": ["contractType", "startDate", "endDate", "status"]
    }
  ],
  "permission": "{AppCode}.{ModuleCode}.Update"
}
```

## SmartDashboard Template

A dashboard component for displaying key performance indicators (KPIs) and data visualizations via charts.

```json
{
  "code": "{module}-dashboard",
  "type": "SmartDashboard",
  "entity": "{PrimaryEntityName}",
  "label": "Tableau de bord {module}",
  "kpis": [
    { "label": "Total actifs", "value": "count(status=Active)", "icon": "users", "color": "primary" },
    { "label": "En conge", "value": "count(status=OnLeave)", "icon": "calendar", "color": "warning" }
  ],
  "charts": [
    { "type": "pie", "label": "Repartition par departement", "dataSource": "employees", "groupBy": "department" },
    { "type": "bar", "label": "Evolution des effectifs", "dataSource": "employees", "groupBy": "hireDate.year" }
  ],
  "permission": "{AppCode}.{ModuleCode}.Read"
}
```

## SmartKanban Template

A board component for workflow-based entities with status columns and draggable cards.

```json
{
  "code": "{entity}-kanban",
  "type": "SmartKanban",
  "entity": "{EntityName}",
  "label": "Kanban {entity}",
  "statusField": "status",
  "columns": [
    { "value": "Draft", "label": "Brouillon", "color": "gray" },
    { "value": "Submitted", "label": "Soumis", "color": "blue" },
    { "value": "Approved", "label": "Approuve", "color": "green" }
  ],
  "cardFields": ["code", "assignee", "dueDate"],
  "permission": "{AppCode}.{ModuleCode}.Read"
}
```

## SmartFilter Template

A dedicated filter component placed before SmartTable in list sections. Do NOT embed filters inside SmartTable — use a separate SmartFilter resource instead.

```json
{
  "code": "{entity-plural}-filters",
  "type": "SmartFilter",
  "entity": "{EntityName}",
  "label": "Filtres {entity-plural}",
  "filters": [
    { "field": "status", "type": "select", "label": "Statut", "options": ["Active", "Inactive"] },
    { "field": "departmentId", "type": "lookup", "label": "Departement", "entity": "Department" },
    { "field": "startDate", "type": "daterange", "label": "Periode" },
    { "field": "search", "type": "text", "label": "Recherche" }
  ],
  "permission": "{AppCode}.{ModuleCode}.Read"
}
```

## SmartCard Template

A card component for displaying entity summaries with avatar, title, subtitle, and action buttons.

```json
{
  "code": "{entity}-card",
  "type": "SmartCard",
  "entity": "{EntityName}",
  "label": "Carte {entity}",
  "title": "fullName",
  "subtitle": "position",
  "fields": [
    { "field": "email", "label": "Email", "icon": "mail" },
    { "field": "department.name", "label": "Departement", "icon": "building" }
  ],
  "avatar": "profileImage",
  "actions": ["view-detail", "edit"],
  "permission": "{AppCode}.{ModuleCode}.Read"
}
```

## Canonical Output Format (screens.json)

The final screens.json file MUST use the sections[] wrapper format:

```json
{
  "sections": [
    {
      "sectionCode": "list",
      "sectionLabel": "Liste des employes",
      "resources": [
        {
          "code": "employees-filters",
          "type": "SmartFilter",
          "entity": "Employee",
          "label": "Filtres employes",
          "filters": [
            { "field": "departmentId", "type": "lookup", "label": "Departement", "entity": "Department" },
            { "field": "status", "type": "select", "label": "Statut", "options": ["Active", "Inactive"] }
          ],
          "permission": "HumanResources.Employees.Read"
        },
        {
          "code": "employees-grid",
          "type": "SmartTable",
          "entity": "Employee",
          "label": "Grille des employes",
          "columns": [],
          "actions": ["create", "export"],
          "rowActions": [
            { "action": "edit", "permission": "HumanResources.Employees.Update" },
            { "action": "view-detail", "permission": "HumanResources.Employees.Read" }
          ],
          "permission": "HumanResources.Employees.Read"
        }
      ]
    },
    {
      "sectionCode": "detail",
      "sectionLabel": "Fiche employe",
      "resources": [
        {
          "code": "employee-form",
          "type": "SmartForm",
          "entity": "Employee",
          "label": "Fiche employe",
          "tabs": [],
          "actions": ["save", "cancel"],
          "permission": "HumanResources.Employees.Update"
        }
      ]
    },
    {
      "sectionCode": "dashboard",
      "sectionLabel": "Tableau de bord",
      "resources": [
        {
          "code": "employees-dashboard",
          "type": "SmartDashboard",
          "entity": "Employee",
          "label": "Tableau de bord RH",
          "kpis": [],
          "charts": [],
          "permission": "HumanResources.Employees.Read"
        }
      ]
    }
  ]
}
```

### Key Naming Requirements

- Use `sectionCode` (not `id` or `code`)
- Use `sectionLabel` (not `displayName` or `label`)
- Resource `type` must be one of: `SmartTable`, `SmartForm`, `SmartDashboard`, `SmartKanban`, `SmartCard`, `SmartFilter`
- The flat `screens[]` format (one object per screen with componentType at top level) is **DEPRECATED** — use `sections[]` instead
