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

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)

{{!-- É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

{{!-- 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

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

Context disponible dans les templates

{
  // 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

// 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 :

{{editor content engine="prosemirror"}}

Actions

Système déclaratif :

actions: {
  myAction: ClassName.#onMyAction
}

Dans le template :

<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
• ItemSheetV2 API
• Exemples : fvtt-cthulhu-eternal, fvtt-mournblade