bol/APPV2_ITEMS_MIGRATION.md

# Migration AppV2 - Item Sheets

## Vue d'ensemble

Migration des feuilles d'items de BoL vers l'architecture **ApplicationV2** de Foundry VTT v12+.

## Fichiers créés

### Classes AppV2 (module/applications/sheets/)

1. **base-item-sheet.mjs** - Classe de base pour tous les item sheets
   - Hérite de `foundry.applications.sheets.ItemSheetV2`
   - Utilise `HandlebarsApplicationMixin`
   - Gère les tabs, drag & drop, actions communes
   - 272 lignes de code

2. **item-sheet.mjs** - Sheet pour le type "item"
   - Équipements, armes, protections, sorts, etc.
   - Hérite de `BoLBaseItemSheet`
   - Contexte spécifique aux items

3. **feature-sheet.mjs** - Sheet pour le type "feature"
   - Boons, flaws, careers, origins, races, etc.
   - Hérite de `BoLBaseItemSheet`
   - Contexte spécifique aux features

4. **_module.mjs** - Export des sheets

### Templates (templates/item/)

1. **item-sheet.hbs** - Template pour les items
2. **feature-sheet.hbs** - Template pour les features  
3. **parts/item-header.hbs** - Header mis à jour pour AppV2

### Backups

- `templates/item.backup/` - Backup des templates originaux
- `module/item.backup/` - Backup de l'ancienne classe ItemSheet
- `templates/item/parts/item-header.hbs.backup` - Backup du header

## Architecture AppV2

### Différences avec AppV1

| Aspect | AppV1 (avant) | AppV2 (après) |
|--------|---------------|---------------|
| Classe de base | `ItemSheet` | `ItemSheetV2` |
| Options | `static get defaultOptions()` | `static DEFAULT_OPTIONS` |
| getData | `async getData()` | `async _prepareContext()` |
| Template | Unique | Peut utiliser PARTS |
| Tabs | Automatiques | Gestion manuelle |
| Actions | Event listeners | `actions:` dans OPTIONS |
| Render | `activateListeners()` | `_onRender()` |

### Structure de BoLBaseItemSheet

```javascript
class BoLBaseItemSheet extends ItemSheetV2 {
  // Options statiques
  static DEFAULT_OPTIONS = {
    classes, position, form, window,
    actions, dragDrop, tabs
  }
  
  // State
  tabGroups = { primary: "description" }
  
  // Méthodes principales
  async _prepareContext()  // Prépare les données
  _onRender()              // Après le render
  _activateTabs()          // Active les tabs
  _activateListeners()     // Event listeners
  
  // Actions
  static #onEditImage()    // data-action="editImage"
  static #onPostItem()     // data-action="postItem"
  
  // Drag & Drop
  #createDragDropHandlers()
  _canDragStart()
  _onDragStart()
}
```

## Fonctionnalités migrées

### ✅ Depuis l'ancien BoLItemSheet

1. **getData** → **_prepareContext**
   - Enrichissement de la description
   - Configuration des données dynamiques
   - Gestion des catégories
   - Propriétés des items
   - Careers depuis l'actor

2. **Tabs**
   - Navigation entre Description et Properties
   - State persistant avec `tabGroups`
   - Activation manuelle des tabs

3. **Actions**
   - Edit Image (FilePicker)
   - Post Item (chat)

4. **Listeners spécifiques**
   - Armor quality → soak formula

5. **Dynamic defaults**
   - Category par défaut
   - Spell conditions (mandatory/optional)
   - Equipment slots

## Utilisation dans les templates

### Actions (data-action)

```handlebars
{{!-- Éditer l'image --}}
<img data-action="editImage" src="{{item.img}}" />

{{!-- Poster au chat --}}
<button data-action="postItem">
  <i class="fas fa-comment"></i>
</button>
```

### Tabs

```handlebars
{{!-- Navigation --}}
<nav class="tabs" data-group="primary">
  {{#each tabs}}
  <a data-tab="{{this.id}}" class="{{#if (eq ../activeTab this.id)}}active{{/if}}">
    {{localize this.label}}
  </a>
  {{/each}}
</nav>

{{!-- Contenu --}}
<div class="tab {{#if (eq activeTab 'description')}}active{{/if}}" 
     data-tab="description">
  ...
</div>
```

### Editor

```handlebars
{{!-- AppV2 avec ProseMirror --}}
{{editor enrichedDescription 
    target="system.description" 
    button=true 
    editable=isEditable 
    engine="prosemirror"}}
```

## Context disponible dans les templates

```javascript
{
  // Document & system
  fields: schema.fields,
  systemFields: system.schema.fields,
  item: document,
  system: document.system,
  source: document.toObject(),
  
  // Content
  enrichedDescription: "HTML enrichi",
  category: "equipment|weapon|spell|...",
  itemProperties: ["prop1", "prop2"],
  
  // Config
  config: game.bol.config,
  isGM: boolean,
  isEditable: boolean,
  
  // Tabs
  tabs: [{id, label, icon}],
  activeTab: "description|properties",
  
  // Type-specific (item-sheet.mjs)
  isItem: true,
  isEquipment: boolean,
  isWeapon: boolean,
  isProtection: boolean,
  isSpell: boolean,
  
  // Type-specific (feature-sheet.mjs)
  isFeature: true,
  isBoon: boolean,
  isFlaw: boolean,
  isCareer: boolean,
  isOrigin: boolean,
  isRace: boolean,
  
  // Optional
  careers: actor.careers  // Si item sur actor
}
```

## Configuration dans bol.js

```javascript
// Import
import * as sheets from "./applications/sheets/_module.mjs"

// Enregistrement
foundry.documents.collections.Items.unregisterSheet("core", ...)
foundry.documents.collections.Items.registerSheet("bol", 
  sheets.BoLItemSheet, 
  { types: ["item"], makeDefault: true }
)
foundry.documents.collections.Items.registerSheet("bol", 
  sheets.BoLFeatureSheet, 
  { types: ["feature"], makeDefault: true }
)
```

## Avantages de AppV2

1. **Performance** : Meilleur rendu et gestion des updates
2. **Structure** : Code plus organisé et maintenable
3. **Actions** : Système d'actions déclaratif
4. **Context** : Préparation des données séparée du template
5. **Standard** : Aligné sur Foundry VTT v12+
6. **Future-proof** : Architecture pérenne

## Points d'attention

### Compatibilité

- Les données restent 100% compatibles
- Seule l'interface de sheet change
- Pas de migration de données nécessaire

### Tabs

Les tabs ne sont plus automatiques dans AppV2 :
- Navigation manuelle avec `_activateTabs()`
- State persistant avec `tabGroups`
- CSS `.active` géré manuellement

### Editor

ProseMirror est maintenant le moteur par défaut :
```handlebars
{{editor content engine="prosemirror"}}
```

### Actions

Système déclaratif :
```javascript
actions: {
  myAction: ClassName.#onMyAction
}
```

Dans le template :
```handlebars
<button data-action="myAction">Click</button>
```

## Prochaines étapes

### Court terme
1. Tester les sheets dans Foundry
2. Vérifier toutes les fonctionnalités
3. Ajuster les CSS si nécessaire

### Moyen terme
4. Migrer les actor sheets vers AppV2
5. Ajouter des features AppV2 (parts, etc.)
6. Optimiser les templates

### Long terme
7. Utiliser PARTS pour modularité
8. Ajouter des actions avancées
9. Améliorer la UX

## Références

- [Foundry AppV2 Documentation](https://foundryvtt.com/api/classes/foundry.applications.api.ApplicationV2.html)
- [ItemSheetV2 API](https://foundryvtt.com/api/classes/foundry.applications.sheets.ItemSheetV2.html)
- Exemples : fvtt-cthulhu-eternal, fvtt-mournblade