# 🏗️ Fluent GUI Builder DSL - betterMcGuis

La création de menus repose sur un pattern **Builder chainable, fluide et modulaire**.

---

## 📑 Sommaire
- [1. Configuration des Dimensions et Types d'Inventaires](#1-configuration-des-dimensions-et-types-dinventaires)
- [2. Placement des Items](#2-placement-des-items)
- [3. Remplissage et Bordures](#3-remplissage-et-bordures)
- [4. Propriétés Dynamiques](#4-propriétés-dynamiques)
- [5. Contrôle du Cycle de Vie et Ouvertures](#5-contrôle-du-cycle-de-vie-et-ouvertures)

---

## 1. Configuration des Dimensions et Types d'Inventaires

Vous pouvez configurer des coffres standards de 1 à 6 lignes, ou des types d'inventaires Bukkit spécifiques :

```java
// Coffre 3 lignes (27 slots)
BetterMcGuis.builder("Titre", 3);

// Types spécifiques via GuiType
BetterMcGuis.builder()
    .title("<yellow>Distributeur</yellow>")
    .type(GuiType.DISPENSER); // DISPENSER, DROPPER, HOPPER, ANVIL, WORKBENCH, BREWING
```

---

## 2. Placement des Items

Vous pouvez positionner des items selon trois méthodes d'adressage :

```java
var builder = BetterMcGuis.builder("Exemple", 4);

// Par slot absolu (0-indexé, 0 à 35)
builder.item(13, monItem);

// Par coordonnées ligne/colonne (0-indexé, ligne 1, col 4)
builder.item(1, 4, monItem);

// Par SlotPos
builder.item(SlotPos.of(1, 4), monItem);
```

---

## 3. Remplissage et Bordures

Des méthodes utilitaires permettent de remplir instantanément l'inventaire ou ses contours :

```java
// Remplit toutes les bordures extérieures avec du vitrage teinté
builder.fillBorder(Material.GRAY_STAINED_GLASS_PANE);

// Remplit une plage continue de slots
builder.fillRange(SlotRange.of(10, 16), monItem);

// Remplit tout l'inventaire
builder.fill(monItem);
```

---

## 4. Propriétés Dynamiques

Vous pouvez attacher des données arbitraires à l'instance de GUI pour les partager entre callbacks :

```java
Gui gui = BetterMcGuis.builder("Profil", 3)
    .property("targetPlayerUuid", target.getUniqueId())
    .property("openedAt", System.currentTimeMillis())
    .build();

// Récupération typée dans un callback
UUID uuid = gui.getProperty("targetPlayerUuid", UUID.class);
```

---

## 5. Contrôle du Cycle de Vie et Ouvertures

* `gui.open(Player)` : Ouvre l'inventaire pour le joueur.
* `gui.close(Player)` : Ferme l'inventaire.
* `gui.refresh(Player)` : Met à jour visuellement les items sans réouverture.
* `gui.refreshAll()` : Rafraîchit l'affichage pour tous les spectateurs actifs.
* `gui.setTitle("<green>Nouveau Titre</green>")` : Modifie le titre du menu.

---

> 📖 **Étape suivante** : Découvrez la création d'items avec [03_ITEM_BUILDER_AND_ITEMS.md](03_ITEM_BUILDER_AND_ITEMS.md).