Un contenu fait de blocs

import { z } from "zod";import { richTextContentSchema } from "@contracts/page/richText";/** * Contrat versionné de contenu de page — v1. * * Une page est composée d'une liste ordonnée de blocs discriminés par * un champ `type`. Six types de blocs sont définis en v1 : * *   - `tiptap`           : texte riche (ProseMirror JSON) *   - `image-gallery`    : galerie d'images *   - `audio-collection` : collection de pistes audio *   - `document-list`    : liste de documents téléchargeables *   - `media-text`       : un média et un texte côte à côte *   - `float-text`       : un texte qui enrobe une image * * Voir README.md pour la philosophie (référence stable par mediaId, * versioning, frontière contrat / builder / renderer). *//* -------------------------------------------------------------------------- *//*  Contenu ProseMirror                                                       *//* -------------------------------------------------------------------------- */// Le texte riche des blocs est validé par `richTextContentSchema` (richText.ts) : une liste// blanche de nœuds, de marques et d'attributs, parce qu'il est rendu en HTML. Le schéma OPAQUE// de shared/prosemirror.ts reste celui des commentaires, que `CommentContent` rend lui-même// sans HTML brut./* -------------------------------------------------------------------------- *//*  Base commune                                                              *//* -------------------------------------------------------------------------- */const blockBaseSchema = z.object({  /**   * Identifiant stable du bloc à l'intérieur de la page.   *   * Généré côté builder (cuid recommandé pour cohérence avec le reste du   * projet), il sert de clé React, de cible de focus/scroll au mount,   * et de point d'ancrage pour le drag-and-drop.   *   * N'est PAS l'identifiant d'un asset — c'est l'identifiant du bloc   * lui-même au sein de la page.   */  id: z.string().min(1),});/* -------------------------------------------------------------------------- *//*  Bloc tiptap                                                               *//* -------------------------------------------------------------------------- */const tiptapBlockSchema = blockBaseSchema.extend({  type: z.literal("tiptap"),  content: richTextContentSchema,});export type TipTapBlockV1 = z.infer<typeof tiptapBlockSchema>;/* -------------------------------------------------------------------------- *//*  Bloc image-gallery                                                        *//* -------------------------------------------------------------------------- */const imageGalleryLayoutSchema = z.enum(["grid", "carousel", "masonry"]);export type ImageGalleryLayout = z.infer<typeof imageGalleryLayoutSchema>;const imageGalleryBlockSchema = blockBaseSchema.extend({  type: z.literal("image-gallery"),  /**   * Liste des images de la galerie.   *   * Volontairement non `.min(1)` : un bloc fraîchement ajouté par le   * builder peut être vide le temps que l'utilisateur sélectionne ses   * premières images via le MediaPicker. La cohérence "non vide à la   * publication" est une décision UX, pas une décision de schema —   * elle pourra être imposée en amont du save par le builder ou par   * une validation côté admin si nécessaire.   */  items: z.array(    z.object({      mediaId: z.string().min(1),      caption: z.string().optional(),    }),  ),  layout: imageGalleryLayoutSchema.default("grid"),});export type ImageGalleryBlockV1 = z.infer<typeof imageGalleryBlockSchema>;/* -------------------------------------------------------------------------- *//*  Bloc audio-collection                                                     *//* -------------------------------------------------------------------------- */const audioCollectionBlockSchema = blockBaseSchema.extend({  type: z.literal("audio-collection"),  items: z.array(    z.object({      mediaId: z.string().min(1),      /** Titre affiché à la place du nom de fichier brut. */      title: z.string().optional(),    }),  ),});export type AudioCollectionBlockV1 = z.infer<typeof audioCollectionBlockSchema>;/* -------------------------------------------------------------------------- *//*  Bloc document-list                                                        *//* -------------------------------------------------------------------------- */const documentListBlockSchema = blockBaseSchema.extend({  type: z.literal("document-list"),  items: z.array(    z.object({      mediaId: z.string().min(1),      /** Libellé du lien (à défaut, on retombe sur le nom de fichier). */      label: z.string().optional(),    }),  ),});export type DocumentListBlockV1 = z.infer<typeof documentListBlockSchema>;/* -------------------------------------------------------------------------- *//*  Bloc media-text                                                           *//* -------------------------------------------------------------------------- *//** * Bloc composite « médias + texte » côte à côte, pensé pour une mise en page * éditoriale. Les DEUX parties sont optionnelles : * *   - `content` + `media` non vides → rendu en deux colonnes ; le RENDERER *     alterne automatiquement le côté des médias d'un bloc media-text au *     suivant (1er : médias à gauche ; 2e : à droite ; etc.). L'ordre n'est *     donc PAS stocké ici — c'est une décision de rendu fondée sur la *     position, pas une donnée du bloc. *   - une seule des deux parties → rendu centré, pleine largeur. * * `media` accepte plusieurs items (images et/ou une vidéo) ; le renderer * décide de leur agencement (grille pour plusieurs images, lecteur pour une * vidéo). `content` est le même ProseMirror JSON que le bloc tiptap. *//** Média issu de la bibliothèque (MediaAsset). */const libraryMediaItemSchema = z.object({  kind: z.literal("library").default("library"),  mediaId: z.string().min(1),  caption: z.string().optional(),});/** * Référence LOGIQUE à l'avatar d'un utilisateur (pas au binaire). Résolue * dynamiquement au rendu : la page affiche toujours l'avatar COURANT du user * — pas de copie, pas de synchro, pas de dérive. Si le user change d'avatar, * la page suit automatiquement. */const avatarMediaItemSchema = z.object({  kind: z.literal("avatar"),  userId: z.string().min(1),  caption: z.string().optional(),});/** * Média d'un bloc media-text : soit un média de bibliothèque, soit une * référence avatar. Discriminé par `kind`. L'ancien format (objet * `{ mediaId }` sans `kind`) est traité comme `library` par le preprocess. *//** * Référence LOGIQUE au logo du site (pas au binaire). Unique — aucun id. Résolue * dynamiquement au rendu via SiteSettings : si l'admin change le logo, toutes les * pages qui l'utilisent suivent. Le logo vit hors finder (clé R2 système). */const siteLogoMediaItemSchema = z.object({  kind: z.literal("site-logo"),  caption: z.string().optional(),});const mediaTextItemSchema = z.discriminatedUnion("kind", [  libraryMediaItemSchema,  avatarMediaItemSchema,  siteLogoMediaItemSchema,]);const mediaTextBlockSchema = blockBaseSchema.extend({  type: z.literal("media-text"),  /** Texte riche optionnel (ProseMirror). Absent/vide → côté texte masqué. */  content: richTextContentSchema.optional(),  /**   * UN SEUL média optionnel : média de bibliothèque OU référence avatar.   * Absent → côté médias masqué.   *   * Compat : preprocess tolérant — (1) un ancien TABLEAU est réduit à son   * premier élément ; (2) un objet SANS `kind` (ancien format média   * bibliothèque) reçoit `kind: "library"`.   */  media: z.preprocess((val) => {    let v = val;    if (Array.isArray(v)) v = v.length > 0 ? v[0] : undefined;    if (      v &&      typeof v === "object" &&      !("kind" in (v as Record<string, unknown>))    ) {      // Ancien format { mediaId, caption } → média bibliothèque.      return { kind: "library", ...(v as Record<string, unknown>) };    }    return v;  }, mediaTextItemSchema.optional()),});export type MediaTextBlockV1 = z.infer<typeof mediaTextBlockSchema>;/* -------------------------------------------------------------------------- *//*  Bloc float-text (texte enrobant une image)                                *//* -------------------------------------------------------------------------- *//** * Une image `float`-ée dans une coulée de texte qui l'enrobe. À distinguer du * média-texte : pas de deux colonnes, pas d'alternance de largeurs. Le `side` * est une DONNÉE du bloc (on choisit où l'illustration se pose), pas une * décision de position — un enrobage n'alterne pas. * * Même modèle de média que le média-texte (bibliothèque OU avatar), réutilisé * via `mediaTextItemSchema` et son preprocess tolérant. */const floatTextBlockSchema = blockBaseSchema.extend({  type: z.literal("float-text"),  content: richTextContentSchema.optional(),  side: z.enum(["left", "right"]).default("left"),  media: z.preprocess((val) => {    let v = val;    if (Array.isArray(v)) v = v.length > 0 ? v[0] : undefined;    if (      v &&      typeof v === "object" &&      !("kind" in (v as Record<string, unknown>))    ) {      return { kind: "library", ...(v as Record<string, unknown>) };    }    return v;  }, mediaTextItemSchema.optional()),});export type FloatTextBlockV1 = z.infer<typeof floatTextBlockSchema>;/* -------------------------------------------------------------------------- *//*  Union discriminée                                                         *//* -------------------------------------------------------------------------- */export const pageBlockSchemaV1 = z.discriminatedUnion("type", [  tiptapBlockSchema,  imageGalleryBlockSchema,  audioCollectionBlockSchema,  documentListBlockSchema,  mediaTextBlockSchema,  floatTextBlockSchema,]);export type PageBlockV1 = z.infer<typeof pageBlockSchemaV1>;/** * Union des `type` littéraux acceptés en v1. * * Pratique pour typer les clés d'un registry — voir * `features/page-builder/blockRegistry.ts` (sous-chantier 5). */export type PageBlockKindV1 = PageBlockV1["type"];/* -------------------------------------------------------------------------- *//*  Enveloppe versionnée                                                      *//* -------------------------------------------------------------------------- */export const pageContentSchemaV1 = z.object({  version: z.literal(1),  blocks: z.array(pageBlockSchemaV1),});export type PageContentV1 = z.infer<typeof pageContentSchemaV1>;/* -------------------------------------------------------------------------- *//*  Helper de fabrique                                                        *//* -------------------------------------------------------------------------- *//** * Fabrique un contenu de page vide, prêt à recevoir des blocs via le * builder. À utiliser comme valeur initiale d'un nouveau Course / Stage / * Post tant que l'admin n'a rien composé. */export function emptyPageContentV1(): PageContentV1 {  return { version: 1, blocks: [] };}

import {  emptyPageContentV1,  pageBlockSchemaV1,  pageContentSchemaV1,  type PageBlockV1,  type PageContentV1,} from '@contracts/page/blocks.v1';/* ─────────────────────────────────────────────────────────────────────── *//*  parsePageContentV1                                                     *//* ─────────────────────────────────────────────────────────────────────── *//** * Lit un `content` brut de la base (typiquement le `Course.content` JSON, * ou `Stage.description` / `Stage.program` / `Post.content`) et rend un * `PageContentV1` toujours valide. * * ─── Pourquoi un helper plutôt qu'un appel direct au schema ? ────────── * * Sur le papier, on pourrait écrire à chaque site d'appel : * *     const parsed = pageContentSchemaV1.safeParse(raw); *     const content = parsed.success ? parsed.data : emptyPageContentV1(); * * Mais ce pattern revient en plusieurs endroits (chaque page publique * qui rend du contenu : `/cours/[id]`, `/stages/[id]`, `/actualites/[id]`, * etc.) et il y a une vraie tentation de l'oublier — ou pire, de jeter * une exception sur les contenus invalides au lieu de dégrader * proprement. * * Le helper porte la **politique de robustesse à la lecture** : un * contenu invalide ou inexistant rend une page vide (avec un éventuel * placeholder côté UI), pas une 500. Cohérent avec le filtrage * silencieux des assets manquants côté Views. * * ─── Quand ça déclenche le fallback ──────────────────────────────────── * *   - `raw` est `null` ou `undefined` (champ jamais peuplé) *   - `raw` est d'une version antérieure incompatible (avant le *     sous-chantier 5, format différent) *   - le `version` est diffèrent de `1` *   - une migration de bloc a partiellement échoué * * Dans tous ces cas, `emptyPageContentV1()` rend `{ version: 1, blocks: [] }`, * qui est sain et rendu en « page vide » par le `PageRenderer`. * * ─── Un bloc fautif ne vide pas la page ─────────────────────────────── * * Une enveloppe v1 dont UN bloc est invalide garde ses autres blocs : seul le * fautif est écarté. Rendre la page entière vide aurait un effet pire qu'à * l'affichage — l'éditeur s'ouvrirait sur une page vide, et l'enregistrer * effacerait tout le reste. * * Chaque écart est signalé par `console.warn` (serveur ou navigateur) : un * contenu qui disparaît sans trace ne se diagnostique pas. */export function parsePageContentV1(raw: unknown): PageContentV1 {  const result = pageContentSchemaV1.safeParse(raw);  if (result.success) return result.data;  if (raw === null || raw === undefined) return emptyPageContentV1();  const envelope = raw as { version?: unknown; blocks?: unknown };  if (envelope.version !== 1 || !Array.isArray(envelope.blocks)) {    console.warn('[parsePageContentV1] contenu illisible, page vide rendue', result.error.issues.slice(0, 3));    return emptyPageContentV1();  }  const blocks: PageBlockV1[] = [];  envelope.blocks.forEach((rawBlock, index) => {    const block = pageBlockSchemaV1.safeParse(rawBlock);    if (block.success) blocks.push(block.data);    else console.warn(`[parsePageContentV1] bloc #${index} écarté`, block.error.issues.slice(0, 3));  });  return { version: 1, blocks };}