feat(admin): sortable form-help blocks with two-panel UI

- Migration 005: add sort_order column to form_help_blocks
- Database: getAllFormHelpBlocks orders by sort_order; new reorderFormHelpBlocks()
- actions/form-help-reorder.php: HTMX POST handler, CSRF-validated, 204 response
- templates/admin/contenus.php: replace flat table with two-panel layout
  - Left: SortableJS 1.15.2 + htmx drag-and-drop ordered block cards
  - Right: static form structure reference showing fieldsets and their inputs
- admin.css: .fhb-* styles for layout, cards, ghost/chosen/drag states, anchors
- schema.sql: updated form_help_blocks DDL with sort_order column

TODO.md

@@ -13,6 +13,19 @@
 
 - [x] Fix `$enabledAccessTypes` undefined / `array_map()` TypeError on edit page — controller was fetching `getAccessTypes()` instead of `getEnabledFormAccessTypes()` and returning it under the wrong key
 
+## Form help blocks — sortable admin UI
+
+- [x] Migration 005: add `sort_order` column to `form_help_blocks`
+- [x] `Database::getAllFormHelpBlocks()` — ORDER BY sort_order, expose sort_order in returned data
+- [x] `Database::reorderFormHelpBlocks(array $keys)` — persist new order
+- [x] `actions/form-help-reorder.php` — HTMX POST handler (CSRF-protected, 204 response)
+- [x] `templates/admin/contenus.php` — replace table with two-panel layout:
+  - Left: SortableJS + htmx drag-and-drop card list
+  - Right: static form structure reference (fieldsets + inputs)
+- [x] CSS in admin.css: `.fhb-*` classes for layout, cards, ghost/chosen/drag states
+- [x] `schema.sql` — updated `form_help_blocks` DDL with `sort_order`
+- [x] Vendor SortableJS 1.15.2 into `assets/js/sortable.min.js` (remove CDN dependency)
+
 ## CSS refactor
 
 - [x] Move semantic HTML element baseline styles into common.css

app/migrations/applied/005_form_help_blocks_sort_order.sql

@@ -0,0 +1,12 @@
+-- Add sort_order to form_help_blocks for drag-and-drop reordering in admin.
+ALTER TABLE form_help_blocks ADD COLUMN sort_order INTEGER NOT NULL DEFAULT 0;
+
+-- Assign initial order matching the canonical FORM_HELP_KEYS array index.
+UPDATE form_help_blocks SET sort_order = 0 WHERE key = 'partage_intro';
+UPDATE form_help_blocks SET sort_order = 1 WHERE key = 'fieldset_tfe_info';
+UPDATE form_help_blocks SET sort_order = 2 WHERE key = 'fieldset_synopsis';
+UPDATE form_help_blocks SET sort_order = 3 WHERE key = 'fieldset_jury';
+UPDATE form_help_blocks SET sort_order = 4 WHERE key = 'fieldset_academic';
+UPDATE form_help_blocks SET sort_order = 5 WHERE key = 'fieldset_files';
+UPDATE form_help_blocks SET sort_order = 6 WHERE key = 'fieldset_access';
+UPDATE form_help_blocks SET sort_order = 7 WHERE key = 'fieldset_email';

app/public/admin/actions/form-help-reorder.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * HTMX handler: persist the new drag-and-drop sort order for form help blocks.
+ *
+ * Expects POST fields:
+ *   csrf_token   — standard admin CSRF token
+ *   block[]      — ordered list of block keys (one hidden input per block, submitted by
+ *                  Sortable+htmx via the form's `end` event trigger)
+ *
+ * Returns a 204 No Content on success (htmx will not swap anything).
+ * On error, returns a 400 with a plain-text message.
+ */
+require_once __DIR__ . '/../../../bootstrap.php';
+require_once __DIR__ . '/../../../src/AdminAuth.php';
+AdminAuth::requireLogin();
+
+if (!isset($_POST['csrf_token'], $_SESSION['csrf_token'])
+    || !hash_equals($_SESSION['csrf_token'], $_POST['csrf_token'])) {
+    http_response_code(403);
+    echo 'Token invalide.';
+    exit;
+}
+
+$keys = $_POST['block'] ?? [];
+if (!is_array($keys) || empty($keys)) {
+    http_response_code(400);
+    echo 'Paramètre block[] manquant.';
+    exit;
+}
+
+// Sanitise: keep only scalar strings, deduplicate.
+$keys = array_values(array_unique(array_filter($keys, 'is_string')));
+
+require_once APP_ROOT . '/src/Database.php';
+$db = new Database();
+
+try {
+    $db->reorderFormHelpBlocks($keys);
+} catch (Exception $e) {
+    error_log('form-help-reorder error: ' . $e->getMessage());
+    http_response_code(500);
+    echo 'Erreur lors de la sauvegarde.';
+    exit;
+}
+
+http_response_code(204);
+exit;

app/public/assets/css/admin.css

@@ -1589,3 +1589,236 @@
     color: var(--text-secondary);
     font-style: italic;
 }
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Form Help Blocks — drag-and-drop builder (contenus.php)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+.fhb-hint {
+    color: var(--text-secondary);
+    font-size: var(--step--1);
+    margin-bottom: var(--space-m);
+}
+
+.fhb-layout {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: var(--space-m);
+    align-items: start;
+    margin-top: var(--space-m);
+}
+
+@media (max-width: 800px) {
+    .fhb-layout {
+        grid-template-columns: 1fr;
+    }
+}
+
+/* ── Panels ─────────────────────────────────────────────────────────────── */
+
+.fhb-sortable-panel,
+.fhb-form-preview-panel {
+    border: 1px solid var(--border-primary);
+    border-radius: 6px;
+    padding: var(--space-s);
+    background: var(--bg-secondary);
+}
+
+.fhb-panel-title {
+    font-size: var(--step-0);
+    font-weight: 600;
+    margin: 0 0 var(--space-3xs) 0;
+    letter-spacing: 0.03em;
+}
+
+.fhb-panel-desc {
+    font-size: var(--step--2);
+    color: var(--text-secondary);
+    margin: 0 0 var(--space-xs) 0;
+}
+
+/* ── Saving indicator ─────────────────────────────────────────────────────── */
+
+.fhb-saving {
+    display: none;
+    align-items: center;
+    gap: var(--space-2xs);
+    font-size: var(--step--1);
+    color: var(--accent-primary);
+    padding: var(--space-2xs) 0;
+}
+
+.fhb-saving.htmx-request {
+    display: flex;
+}
+
+/* ── Draggable block cards ─────────────────────────────────────────────────── */
+
+.fhb-sortable {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2xs);
+    padding: 0;
+    margin: 0;
+}
+
+.fhb-block-card {
+    display: flex;
+    align-items: center;
+    gap: var(--space-xs);
+    background: var(--bg-primary);
+    border: 1px solid var(--border-primary);
+    border-left: 4px solid var(--accent-primary);
+    border-radius: 4px;
+    padding: var(--space-2xs) var(--space-xs);
+    cursor: default;
+    transition: box-shadow 0.15s, border-color 0.15s;
+}
+
+.fhb-block-card:hover {
+    box-shadow: 0 2px 8px rgba(0,0,0,0.08);
+    border-color: var(--accent-primary);
+}
+
+.fhb-drag-handle {
+    font-size: 1.2em;
+    color: var(--text-tertiary);
+    cursor: grab;
+    flex-shrink: 0;
+    line-height: 1;
+    user-select: none;
+    padding: 2px 4px;
+}
+
+.fhb-drag-handle:active {
+    cursor: grabbing;
+}
+
+.fhb-block-info {
+    flex: 1;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+}
+
+.fhb-block-label {
+    font-size: var(--step--1);
+    font-weight: 500;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.fhb-block-preview {
+    font-size: var(--step--2);
+    color: var(--text-secondary);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.fhb-block-empty {
+    font-size: var(--step--2);
+    color: var(--text-tertiary);
+    font-style: italic;
+}
+
+.fhb-edit-btn {
+    flex-shrink: 0;
+    font-size: var(--step--2) !important;
+    padding: 2px var(--space-xs) !important;
+}
+
+/* ── SortableJS state classes ─────────────────────────────────────────────── */
+
+.fhb-ghost {
+    opacity: 0.35;
+    background: var(--accent-muted);
+    border-color: var(--accent-primary);
+}
+
+.fhb-chosen {
+    box-shadow: 0 4px 16px rgba(149, 87, 181, 0.25);
+    border-color: var(--accent-primary);
+}
+
+.fhb-dragging {
+    opacity: 0.9;
+    box-shadow: 0 8px 24px rgba(0,0,0,0.15);
+}
+
+/* ── Form structure preview (right panel) ─────────────────────────────────── */
+
+.fhb-form-preview {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2xs);
+}
+
+.fhb-fieldset-preview {
+    border: 1px solid var(--border-secondary);
+    border-radius: 4px;
+    padding: var(--space-xs);
+    background: var(--bg-primary);
+}
+
+.fhb-fieldset-legend {
+    font-size: var(--step--1);
+    font-weight: 600;
+    color: var(--text-primary);
+    margin-bottom: var(--space-3xs);
+    padding-bottom: var(--space-3xs);
+    border-bottom: 1px solid var(--border-primary);
+}
+
+.fhb-fieldset-inputs {
+    margin: 0;
+    padding: 0 0 0 var(--space-s);
+    list-style: disc;
+}
+
+.fhb-fieldset-inputs li {
+    font-size: var(--step--2);
+    color: var(--text-secondary);
+    line-height: 1.6;
+}
+
+.fhb-anchor {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2xs);
+    border-radius: 4px;
+    padding: var(--space-3xs) var(--space-xs);
+    font-size: var(--step--2);
+    border: 1px dashed var(--border-primary);
+    background: transparent;
+}
+
+.fhb-anchor--filled {
+    border-color: var(--accent-primary);
+    background: var(--accent-muted);
+    color: var(--accent-secondary);
+}
+
+.fhb-anchor--empty {
+    color: var(--text-tertiary);
+}
+
+.fhb-anchor-icon {
+    flex-shrink: 0;
+    font-style: normal;
+}
+
+.fhb-anchor-label {
+    flex: 1;
+}
+
+.fhb-anchor-pos {
+    font-size: var(--step--2);
+    font-weight: 600;
+    color: var(--accent-primary);
+    background: var(--accent-muted);
+    border-radius: 2px;
+    padding: 0 4px;
+}

app/src/Database.php

@@ -2039,20 +2039,39 @@ class Database {
     }
 
     /**
-     * Return all form help blocks as [ key => ['content' => ..., 'updated_at' => ...] ].
+     * Return all form help blocks ordered by sort_order, as [ key => ['content' => ..., 'updated_at' => ..., 'sort_order' => ...] ].
      */
     public function getAllFormHelpBlocks(): array {
         $stmt = $this->pdo->query(
-            "SELECT key, content, updated_at FROM form_help_blocks ORDER BY key"
+            "SELECT key, content, updated_at, sort_order FROM form_help_blocks ORDER BY sort_order, key"
         );
         $rows = $stmt->fetchAll();
         $out  = [];
         foreach ($rows as $r) {
-            $out[$r['key']] = ['content' => $r['content'], 'updated_at' => $r['updated_at']];
+            $out[$r['key']] = [
+                'content'    => $r['content'],
+                'updated_at' => $r['updated_at'],
+                'sort_order' => (int)$r['sort_order'],
+            ];
         }
         return $out;
     }
 
+    /**
+     * Persist a new sort order for all form help blocks.
+     * $keys must be an ordered array of known block keys.
+     */
+    public function reorderFormHelpBlocks(array $keys): void {
+        $stmt = $this->pdo->prepare(
+            "UPDATE form_help_blocks SET sort_order = ? WHERE key = ?"
+        );
+        foreach ($keys as $i => $key) {
+            if (in_array($key, self::FORM_HELP_KEYS, true)) {
+                $stmt->execute([$i, $key]);
+            }
+        }
+    }
+
     // ========================================================================
     // SINGLETON PATTERN ENFORCEMENT
     // ========================================================================

app/templates/admin/contenus.php

@@ -69,37 +69,158 @@
         </tbody>
     </table>
 
+    <!-- ═══════════════════════════════════════════════════════════════════
+         Blocs d'aide du formulaire étudiant·e
+         ═══════════════════════════════════════════════════════════════════ -->
     <h2 id="form-help-blocks" style="margin-top:2rem;">Blocs d'aide du formulaire étudiant·e</h2>
-    <p>Ces textes apparaissent dans le formulaire de soumission accessible via les liens de partage. Ils permettent d'expliquer aux étudiant·es comment remplir chaque section. Supporte le Markdown.</p>
+    <p>Ces textes apparaissent dans le formulaire de soumission accessible via les liens de partage.
+       Ils permettent d'expliquer aux étudiant·es comment remplir chaque section. Supporte le Markdown.</p>
+    <p class="fhb-hint">
+        <strong>Glissez</strong> les blocs d'aide (cartes violettes) pour les réorganiser dans le formulaire.
+        Cliquez sur <strong>Éditer</strong> pour modifier le contenu d'un bloc.
+        L'ordre est sauvegardé automatiquement après chaque déplacement.
+    </p>
+
+    <?php
+    // Build an ordered flat list of all blocks for the sortable form.
+    // $formHelpBlocks is keyed by block key, already sorted by sort_order.
+    $orderedBlocks = [];
+    foreach ($formHelpBlocks as $key => $block) {
+        $orderedBlocks[] = array_merge($block, [
+            'key'   => $key,
+            'label' => Database::FORM_HELP_LABELS[$key] ?? $key,
+        ]);
+    }
+
+    // Static form structure: each item is either a 'fieldset' (visual container)
+    // or an 'anchor' for a specific block key showing where it sits in the form.
+    // We also need a mapping from block key → where it currently sits in the sorted list.
+    // The entire sorted order is what matters; we render the form structure as a visual
+    // reference alongside the sortable list.
+    $formStructure = [
+        ['type' => 'anchor', 'key' => 'partage_intro',     'position' => 'before-form',   'label' => 'Avant le formulaire (introduction)'],
+        ['type' => 'fieldset', 'name' => 'Informations du TFE', 'inputs' => ['Titre', 'Sous-titre', 'Auteur·ice(s)', 'Contact', 'Synopsis']],
+        ['type' => 'anchor', 'key' => 'fieldset_tfe_info',  'position' => 'intro-fieldset', 'label' => 'Intro du fieldset « Informations du TFE »'],
+        ['type' => 'anchor', 'key' => 'fieldset_synopsis',  'position' => 'intro-fieldset', 'label' => 'Note sous le champ Synopsis'],
+        ['type' => 'fieldset', 'name' => 'Composition du jury', 'inputs' => ['Président·e', 'Promoteur·ice', 'Lecteur·ices (×4)']],
+        ['type' => 'anchor', 'key' => 'fieldset_jury',      'position' => 'intro-fieldset', 'label' => 'Intro du fieldset « Jury »'],
+        ['type' => 'fieldset', 'name' => 'Cadre académique', 'inputs' => ['Année', 'Orientation', 'AP', 'Finalité', 'Langues', 'Formats', 'Mots-clés']],
+        ['type' => 'anchor', 'key' => 'fieldset_academic',  'position' => 'intro-fieldset', 'label' => 'Intro du fieldset « Cadre académique »'],
+        ['type' => 'fieldset', 'name' => 'Fichiers', 'inputs' => ['Fichier principal (PDF)', 'Annexes']],
+        ['type' => 'anchor', 'key' => 'fieldset_files',     'position' => 'intro-fieldset', 'label' => 'Intro du fieldset « Fichiers »'],
+        ['type' => 'fieldset', 'name' => 'Visibilité / Accès', 'inputs' => ["Type d'accès", 'Licence']],
+        ['type' => 'anchor', 'key' => 'fieldset_access',    'position' => 'intro-fieldset', 'label' => 'Intro du fieldset « Visibilité »'],
+        ['type' => 'fieldset', 'name' => 'E-mail de confirmation', 'inputs' => ['Adresse e-mail']],
+        ['type' => 'anchor', 'key' => 'fieldset_email',     'position' => 'intro-fieldset', 'label' => 'Intro du fieldset « E-mail »'],
+    ];
+    ?>
+
+    <div class="fhb-layout">
+
+        <!-- Left: sortable ordered list of help blocks -->
+        <div class="fhb-sortable-panel">
+            <h3 class="fhb-panel-title">Ordre des blocs</h3>
+            <p class="fhb-panel-desc">Glissez pour réorganiser</p>
+
+            <form class="fhb-sortable sortable"
+                  hx-post="/admin/actions/form-help-reorder.php"
+                  hx-trigger="end"
+                  hx-include="this"
+                  hx-swap="none">
+                <input type="hidden" name="csrf_token" value="<?= htmlspecialchars($_SESSION['csrf_token']) ?>">
+                <div class="htmx-indicator fhb-saving">Sauvegarde…</div>
+
+                <?php foreach ($orderedBlocks as $b): ?>
+                <div class="fhb-block-card" data-key="<?= htmlspecialchars($b['key']) ?>">
+                    <input type="hidden" name="block[]" value="<?= htmlspecialchars($b['key']) ?>">
+                    <span class="fhb-drag-handle" aria-hidden="true">⠿</span>
+                    <div class="fhb-block-info">
+                        <span class="fhb-block-label"><?= htmlspecialchars($b['label']) ?></span>
+                        <?php if (trim($b['content']) !== ''): ?>
+                        <span class="fhb-block-preview"><?= htmlspecialchars(mb_strimwidth(trim($b['content']), 0, 60, '…')) ?></span>
+                        <?php else: ?>
+                        <span class="fhb-block-empty">— vide —</span>
+                        <?php endif; ?>
+                    </div>
+                    <a href="/admin/contenus-edit.php?form_block=<?= urlencode($b['key']) ?>"
+                       class="admin-btn admin-btn--sm fhb-edit-btn">Éditer</a>
+                </div>
+                <?php endforeach; ?>
+            </form>
+        </div>
+
+        <!-- Right: static form structure reference -->
+        <div class="fhb-form-preview-panel">
+            <h3 class="fhb-panel-title">Structure du formulaire</h3>
+            <p class="fhb-panel-desc">Référence visuelle — non modifiable</p>
+
+            <div class="fhb-form-preview">
+                <?php foreach ($formStructure as $item): ?>
+                    <?php if ($item['type'] === 'anchor'): ?>
+                    <?php
+                        $bData = $formHelpBlocks[$item['key']] ?? ['content' => '', 'sort_order' => 99];
+                        $hasContent = trim($bData['content'] ?? '') !== '';
+                    ?>
+                    <div class="fhb-anchor <?= $hasContent ? 'fhb-anchor--filled' : 'fhb-anchor--empty' ?>">
+                        <span class="fhb-anchor-icon"><?= $hasContent ? '✎' : '○' ?></span>
+                        <span class="fhb-anchor-label"><?= htmlspecialchars(Database::FORM_HELP_LABELS[$item['key']] ?? $item['key']) ?></span>
+                        <?php if ($hasContent): ?>
+                        <span class="fhb-anchor-pos">#<?= (int)$bData['sort_order'] + 1 ?></span>
+                        <?php endif; ?>
+                    </div>
+                    <?php elseif ($item['type'] === 'fieldset'): ?>
+                    <div class="fhb-fieldset-preview">
+                        <div class="fhb-fieldset-legend"><?= htmlspecialchars($item['name']) ?></div>
+                        <ul class="fhb-fieldset-inputs">
+                            <?php foreach ($item['inputs'] as $inp): ?>
+                            <li><?= htmlspecialchars($inp) ?></li>
+                            <?php endforeach; ?>
+                        </ul>
+                    </div>
+                    <?php endif; ?>
+                <?php endforeach; ?>
+            </div>
+        </div>
+
+    </div><!-- /.fhb-layout -->
 
-    <table>
-        <thead>
-            <tr>
-                <th scope="col">Bloc</th>
-                <th scope="col">Aperçu</th>
-                <th scope="col">Mis à jour</th>
-                <th scope="col">Action</th>
-            </tr>
-        </thead>
-        <tbody>
-            <?php foreach (Database::FORM_HELP_KEYS as $key): ?>
-            <?php
-                $block   = $formHelpBlocks[$key] ?? ['content' => '', 'updated_at' => null];
-                $label   = Database::FORM_HELP_LABELS[$key] ?? $key;
-                $preview = $block['content'] !== ''
-                    ? mb_strimwidth($block['content'], 0, 80, '…')
-                    : '<em class="muted">— vide —</em>';
-            ?>
-            <tr>
-                <td><?= htmlspecialchars($label) ?></td>
-                <td><small><?= $block['content'] !== '' ? htmlspecialchars($preview) : $preview ?></small></td>
-                <td><?= htmlspecialchars($block['updated_at'] ?? '—') ?></td>
-                <td>
-                    <a href="/admin/contenus-edit.php?form_block=<?= urlencode($key) ?>"
-                       class="admin-btn admin-btn--sm">Éditer</a>
-                </td>
-            </tr>
-            <?php endforeach; ?>
-        </tbody>
-    </table>
 </main>
+
+<script>
+(function () {
+    var script = document.createElement('script');
+    script.src = '<?= App::assetV('/assets/js/sortable.min.js') ?>';
+    script.onload = initSortable;
+    document.head.appendChild(script);
+
+    function initSortable() {
+        htmx.onLoad(function (content) {
+            var sortables = content.querySelectorAll('.sortable');
+            for (var i = 0; i < sortables.length; i++) {
+                (function (sortable) {
+                    var sortableInstance = new Sortable(sortable, {
+                        animation: 150,
+                        handle: '.fhb-drag-handle',
+                        ghostClass: 'fhb-ghost',
+                        chosenClass: 'fhb-chosen',
+                        dragClass: 'fhb-dragging',
+
+                        filter: '.htmx-indicator',
+                        onMove: function (evt) {
+                            return evt.related.className.indexOf('htmx-indicator') === -1;
+                        },
+
+                        onEnd: function () {
+                            this.option('disabled', true);
+                        }
+                    });
+
+                    sortable.addEventListener('htmx:afterRequest', function () {
+                        sortableInstance.option('disabled', false);
+                    });
+                })(sortables[i]);
+            }
+        });
+    }
+})();
+</script>