# Format de fichier Tabler (.table.md)
> Documentation technique — ProAppli Tabler

---

## Vue d'ensemble

Un fichier `.table.md` est un fichier Markdown standard contenant un tableau, précédé d'un **front matter YAML** qui définit les propriétés de chaque colonne.

```
---
[Front Matter : métadonnées + définitions de champs]
---

| colonne1 | colonne2 | colonne3 |
| -------- | -------- | -------- |
| valeur   | valeur   | valeur   |
```

Le fichier est lisible et éditable avec n'importe quel éditeur de texte. Les IA (ChatGPT, Claude, Grok…) comprennent et génèrent nativement ce format.

---

## 1. Front Matter (entête YAML)

Délimité par `---` en début de fichier. Contient une ligne `#meta` optionnelle et une définition par champ.

```yaml
---
#meta title=Contacts icon=👤
name: type=text label=Nom
email: type=email label=Email
age: type=number label=Âge
---
```

### 1.1 Ligne `#meta` (optionnelle)

Métadonnées globales du fichier. Utilisée principalement par le système de modèles.

```
#meta title=Contacts icon=👤
```

| Propriété | Description |
|-----------|-------------|
| `title`   | Nom affiché dans le sélecteur de modèles |
| `icon`    | Emoji affiché comme icône du modèle |

### 1.2 Définition d'un champ

Chaque ligne définit une colonne du tableau :

```
nom_technique: propriété1=valeur1 propriété2=valeur2
```

Le **nom technique** (avant le `:`) est le nom de la colonne dans le tableau Markdown. Il sert d'identifiant interne et est utilisé dans les formules. Il doit être en caractères simples, sans espaces (utiliser des underscores).

Le **label** (propriété optionnelle) est le nom affiché dans l'interface. Il peut contenir des espaces s'il est entre guillemets.

```
postal_code: type=text label="Code postal"
```

---

## 2. Propriétés des champs

### 2.1 Type de données (`type=`)

Définit la nature de la donnée. Contrôle la validation et le formatage.

| Type | Description | Exemple de valeur |
|------|-------------|-------------------|
| `text` | Texte libre (défaut) | `Dupont` |
| `number` | Nombre entier ou décimal | `42`, `3.14` |
| `currency` | Montant monétaire | `1500.00` |
| `percent` | Pourcentage | `75` (affiché 75%) |
| `date` | Date | `2025-01-15` |
| `time` | Heure | `14:30` |
| `datetime` | Date et heure | `2025-01-15T14:30` |
| `email` | Adresse email | `jean@exemple.fr` |
| `url` | Lien web | `https://exemple.fr` |
| `phone` | Numéro de téléphone | `+33 6 12 34 56 78` |
| `boolean` | Vrai/Faux | `true`, `false` |
| `color` | Couleur hexadécimale | `#ff6600` |
| `image` | URL d'image | `https://exemple.fr/photo.jpg` |
| `file` | Chemin de fichier | `documents/rapport.pdf` |

### 2.2 Mode de saisie (`input=`)

Définit le widget d'édition affiché dans l'interface.

| Input | Description | Propriétés associées |
|-------|-------------|---------------------|
| `input` | Champ texte simple (défaut) | — |
| `select` | Liste déroulante | `values=opt1,opt2,opt3` |
| `checkbox` | Case à cocher | — |
| `radio` | Boutons radio | `values=opt1,opt2` |
| `textarea` | Zone de texte multiligne | — |
| `formula` | Champ calculé (non éditable) | `formula=expression` |
| `rating` | Étoiles cliquables (1 à N) | `max=5` (défaut : 5) |

### 2.3 Propriétés complémentaires

| Propriété | Description | Exemple |
|-----------|-------------|---------|
| `label` | Libellé affiché (si différent du nom technique) | `label="Code postal"` |
| `values` | Valeurs possibles (pour select/radio), séparées par des virgules | `values=faible,moyen,fort` |
| `formula` | Expression de calcul référençant d'autres colonnes | `formula=price_ht*(1+vat/100)` |
| `default` | Valeur par défaut pour les nouvelles lignes | `default=0` |
| `currency` | Symbole monétaire | `currency=€`, `currency=$` |
| `max` | Nombre max d'étoiles (pour rating) | `max=5` |
| `required` | Champ obligatoire (flag sans valeur) | `required` |
| `aggregations` | Calculs affichés en pied de tableau, séparés par des virgules | `aggregations=sum,average` |

### 2.4 Agrégations disponibles

Les agrégations s'affichent automatiquement dans une ligne de pied de tableau.

| Agrégation | Symbole | Description |
|------------|---------|-------------|
| `sum` | Σ | Somme de la colonne |
| `average` | μ | Moyenne de la colonne |
| `min` | ↓ | Valeur minimale |
| `max` | ↑ | Valeur maximale |
| `count` | # | Nombre de valeurs non vides |

Exemple : `aggregations=sum,average` affiche la somme et la moyenne en bas de la colonne.

---

## 3. Corps du tableau (Markdown)

Le tableau suit le standard Markdown :

```markdown
| name   | email            | age |
| ------ | ---------------- | --- |
| Dupont | jean@exemple.fr  | 42  |
| Martin | anne@exemple.fr   | 35  |
|        |                  |     |
```

### Règles

- La première ligne contient les **noms techniques** des colonnes (ceux définis dans le front matter).
- La deuxième ligne est le **séparateur** composé de tirets (`---`).
- Les lignes suivantes sont les **données**.
- Les lignes vides (`|  |  |  |`) sont des lignes sans données, elles sont préservées.
- Les cellules sont séparées par des pipes `|`.
- Les espaces autour des valeurs sont ignorés.

---

## 4. Formules

Les formules référencent les autres colonnes par leur **nom technique**.

### Opérateurs supportés

| Opérateur | Description |
|-----------|-------------|
| `+` `-` `*` `/` | Arithmétique de base |
| `(` `)` | Groupement |

### Exemples

```
# Prix TTC calculé depuis HT et TVA
price_ttc: type=currency input=formula formula=price_ht*(1+vat/100) currency=€

# Reste à dépenser
remaining: type=currency input=formula formula=budget-spent currency=€

# Marge en pourcentage
margin: type=percent input=formula formula=(revenue-cost)/revenue*100
```

Les formules sont recalculées automatiquement à chaque modification d'une cellule.

---

## 5. Guillemets dans le front matter

Les valeurs contenant des **espaces** doivent être entre guillemets doubles :

```
postal_code: type=text label="Code postal"
full_name: type=text label="Nom complet"
status: type=text input=select values=todo,in_progress,done label="État"
```

Les valeurs sans espaces n'ont pas besoin de guillemets :

```
name: type=text label=Nom
age: type=number label=Âge
```

---

## 6. Exemples complets

### 6.1 Gestion de contacts

```markdown
---
#meta title=Contacts icon=👤
name: type=text label=Nom
first_name: type=text label="Prénom"
title: type=text input=select values=M.,Mme,Dr,Me,Pr label="Civilité"
company: type=text label="Société"
email: type=email label=Email
phone: type=phone label="Téléphone"
category: type=text input=select values=client,prospect,fournisseur,partenaire label="Catégorie"
city: type=text label=Ville
notes: type=text input=textarea label=Notes
active: type=boolean input=checkbox label=Actif
---

| name    | first_name | title | company     | email               | phone          | category | city       | notes           | active |
| ------- | ---------- | ----- | ----------- | ------------------- | -------------- | -------- | ---------- | --------------- | ------ |
| Dupont  | Marie      | Mme   | Acme SA     | marie@acme.fr       | 01 23 45 67 89 | client   | Paris      | Compte premium  | true   |
| Martin  | Pierre     | M.    | Tech Corp   | p.martin@tech.fr    | 06 12 34 56 78 | prospect | Lyon       |                 | true   |
| Durand  | Sophie     | Dr    | MedLab      | s.durand@medlab.fr  | 04 56 78 90 12 | partenaire | Marseille |                 | false  |
```

### 6.2 Catalogue produits avec formules

```markdown
---
#meta title=Produits icon=📦
reference: type=text label="Référence"
name: type=text label=Nom
price_ht: type=currency currency=€ label="Prix HT" aggregations=sum
vat: type=percent label=TVA default=20
price_ttc: type=currency input=formula formula=price_ht*(1+vat/100) currency=€ label="Prix TTC"
stock: type=number label=Stock aggregations=sum
status: type=text input=select values=actif,épuisé,abandonné label=Statut
---

| reference | name              | price_ht | vat | price_ttc | stock | status |
| --------- | ----------------- | -------- | --- | --------- | ----- | ------ |
| PRD-001   | Licence Standard  | 49.00    | 20  |           | 500   | actif  |
| PRD-002   | Licence Pro       | 99.00    | 20  |           | 200   | actif  |
| PRD-003   | Formation 1 jour  | 450.00   | 20  |           | 10    | actif  |
```

> Les cellules `price_ttc` sont vides dans le fichier source : elles sont calculées automatiquement à l'affichage.

### 6.3 Suivi de projet

```markdown
---
#meta title=Projets icon=📊
project: type=text label=Projet
owner: type=text label=Responsable
status: type=text input=select values=planifié,en_cours,en_pause,terminé,annulé label=Statut
start_date: type=date label=Début
end_date: type=date label=Fin
budget: type=currency currency=€ label=Budget aggregations=sum
spent: type=currency currency=€ label=Dépensé aggregations=sum
remaining: type=currency input=formula formula=budget-spent currency=€ label=Reste aggregations=sum
progress: type=percent label=Avancement aggregations=average
risk: type=text input=select values=faible,moyen,élevé,critique label=Risque
---

| project         | owner   | status   | start_date | end_date   | budget   | spent    | remaining | progress | risk   |
| --------------- | ------- | -------- | ---------- | ---------- | -------- | -------- | --------- | -------- | ------ |
| Refonte site    | Marie   | en_cours | 2025-01-15 | 2025-06-30 | 15000.00 | 8500.00  |           | 55       | moyen  |
| App mobile      | Pierre  | planifié | 2025-03-01 | 2025-09-30 | 25000.00 | 0        |           | 0        | élevé  |
| Migration cloud | Sophie  | en_cours | 2025-02-01 | 2025-04-30 | 8000.00  | 6200.00  |           | 80       | faible |
```

### 6.4 Quiz / QCM

```markdown
---
#meta title=Quiz icon=❓
order_num: type=number label=N°
question: type=text input=textarea label=Question
type: type=text input=select values=qcm,vrai_faux,ouverte label=Type
choice_a: type=text label="Choix A"
choice_b: type=text label="Choix B"
choice_c: type=text label="Choix C"
choice_d: type=text label="Choix D"
answer: type=text label=Réponse
explanation: type=text input=textarea label=Explication
points: type=number label=Points aggregations=sum
difficulty: type=text input=select values=facile,moyen,difficile label="Difficulté"
---

| order_num | question                              | type      | choice_a | choice_b  | choice_c  | choice_d | answer | explanation                    | points | difficulty |
| --------- | ------------------------------------- | --------- | -------- | --------- | --------- | -------- | ------ | ------------------------------ | ------ | ---------- |
| 1         | Quelle est la capitale de la France ? | qcm       | Lyon     | Paris     | Marseille | Lille    | B      | Paris est la capitale depuis…  | 1      | facile     |
| 2         | Le soleil tourne autour de la Terre   | vrai_faux | Vrai     | Faux      |           |          | B      | C'est la Terre qui tourne…     | 1      | facile     |
| 3         | Expliquez la photosynthèse            | ouverte   |          |           |           |          |        | Processus par lequel…          | 3      | difficile  |
```

---

## 7. Modèles (templates)

Les modèles sont des fichiers `.table.md` standard placés dans le dossier `_templates/` à côté de `tabler.php`.

```
tabler.php
tabler.js
tabler.css
_templates/
  ├── contacts.table.md
  ├── products.table.md
  ├── tasks.table.md
  └── ...
```

Pour créer un nouveau modèle : créez un fichier `.table.md` avec le front matter et quelques lignes d'exemple, placez-le dans `_templates/`. Il apparaîtra automatiquement dans le sélecteur de modèles.

La ligne `#meta` est utilisée pour l'affichage dans le sélecteur :

```
#meta title="Mon modèle" icon=🎯
```

---

## 8. Compatibilité et interopérabilité

| Outil | Import | Export |
|-------|--------|--------|
| **ProAppli Tabler** | ✅ Natif | ✅ Natif |
| **Excel / LibreOffice** | ✅ Copier-coller | ✅ Export .xlsx |
| **Éditeur de texte** (VS Code, Notepad…) | ✅ Lecture/écriture directe | ✅ Fichier texte standard |
| **Git** | ✅ Versionnable (diff lisible) | ✅ Texte brut |
| **IA** (ChatGPT, Claude, Grok…) | ✅ Comprend le format nativement | ✅ Génère du Markdown table |
| **Marp** | ⚠️ Front matter différent | ⚠️ Tableau affiché sans types |

---

## 9. Règles importantes

- Le front matter est **optionnel**. Un fichier `.table.md` sans front matter est simplement un tableau Markdown classique — il fonctionnera mais sans typage ni formules.
- Les noms de colonnes dans le front matter **doivent correspondre exactement** aux en-têtes du tableau Markdown.
- Les colonnes présentes dans le tableau mais absentes du front matter sont traitées comme `type=text`.
- Les formules référencent les colonnes par leur **nom technique** (celui du front matter), pas par leur label.
- Les valeurs de cellules `formula` peuvent être laissées vides dans le fichier source : elles sont calculées à l'affichage.
- Le séparateur `| --- | --- |` doit contenir au moins un tiret par colonne.