Contratti dei tipi di blocco

Questo documento è nato come inventario della Fase 1 dei tipi di blocco core pubblicati attualmente distribuiti in WebBlocks CMS, ora documenta anche la vista di contratto in sola lettura dell'area di amministrazione della Fase 2 e registra le correzioni di standardizzazione delle lacune della Fase 3 completate finora, inclusa la pulizia Layout + Card per section, container, grid, cluster, card e content_header, la pulizia Marketing / Contenuti strutturati per hero, columns, column_item, cta, feature-grid e feature-item, e la pulizia Legacy / Transitional che mantiene documentati in modo trasparente i vecchi slug di compatibilità senza promuoverli nel catalogo core pubblicato.

La Fase 1 è esclusivamente documentazione in sola lettura.

• Non ridisegna i form dei blocchi.
• Non aggiunge un costruttore di form basato su database.
• Non migra il contenuto dei blocchi.
• Non modifica il rendering pubblico.
• Non modifica il funzionamento attuale delle modifiche in Admin -> System -> Block Types.

L'attuale schermata di amministrazione Block Types resta una schermata di catalogo e metadati. Nella Fase 2 può ora aprire un modale Contract in sola lettura per ogni riga elencata, ma non è ancora un costruttore di form dinamico né un editor di schemi.

La Fase 3 dei plugin aggiunge hook di blocco per plugin di sola dichiarazione tramite PluginBlockTypeDefinition, PluginBlockPackDefinition e PluginBlockRegistry. I plugin abilitati possono esporre handle di proprietà del plugin come analytics-tools::score-card ai fini della scoperta, ma tali dichiarazioni non sostituiscono i contratti dei blocchi core distribuiti, le view dei blocchi core, i seeder core o i servizi di modifica dei blocchi. Gli handle non qualificati in stile core come hero restano di proprietà del core e vengono rifiutati nelle dichiarazioni dei plugin.

Un contratto di tipo di blocco è l'accordo tecnico attuale su come un tipo di blocco si comporta nei diversi livelli del CMS:

• identità di catalogo: slug, etichetta, categoria, stato e metadati di sistema o di contenitore
• origine del form di amministrazione: quale partial Blade modifica attualmente il blocco e quali campi espone
• validazione e gestione delle richieste: come App\Http\Requests\Admin\BlockRequest normalizza e valida attualmente i payload dei blocchi
• proprietà dello storage: quali valori risiedono in blocks, in righe di traduzione dedicate, in block_media o in record correlati
• proprietà della traduzione: quali campi rivolti all'utente appartengono alla lingua
• proprietà condivisa: quali impostazioni o relazioni restano condivise tra le lingue
• proprietà di media o relazioni: media_id diretto, block_media ordinato, lookup di navigazione o relazioni nella stessa pagina
• supporto dei figli: se il blocco è un contenitore e se i tipi figli sono limitati
• origine del renderer pubblico: quale partial Blade pubblico esegue oggi il rendering del blocco
• contratto della radice del renderer: se il blocco possiede il proprio markup radice pubblico oppure si affida al percorso generico del wrapper
• portabilità e revisioni: se l'attuale forma di storage debba continuare a viaggiare attraverso revisioni, clonazione, esportazione/importazione e promozione
• test e lacune: copertura mirata nota, comportamenti poco chiari o debito di compatibilità

Termini di stato usati di seguito:

• clear: form di amministrazione, gestione delle richieste, storage e renderer sono sostanzialmente allineati
• mostly clear: il contratto attuale è comprensibile ma presenta un'avvertenza rilevante
• transitional: il contratto attuale mantiene intenzionalmente un percorso di compatibilità o uno schema di proprietà misto
• needs review: i percorsi di codice attuali sono in disaccordo oppure il comportamento è documentato in modo così insufficiente che la Fase 2 dovrebbe evidenziarlo più chiaramente
• legacy/fallback: il comportamento pubblicato dipende da un percorso di fallback o di compatibilità

Il lavoro attuale e futuro sui contratti dovrebbe mantenere esplicite queste regole di proprietà:

• i testi rivolti all'utente appartengono alle righe di traduzione quando il blocco appartiene a una lingua
• i dati operativi o di impostazione condivisi appartengono alle impostazioni condivise del blocco o a relazioni esplicite
• i media dovrebbero usare i percorsi di proprietà media_id o block_media ove applicabile
• evitate di spostare contenuti rivolti all'utente in un JSON di impostazioni arbitrario
• mantenete documentati i percorsi di storage di compatibilità finché continuano a influenzare l'output pubblico o le importazioni

Questo inventario della Fase 1 si basa sul codice sorgente distribuito, non su supposizioni.

• sorgente del catalogo: app/Support/Blocks/CoreBlockTypeCatalogSyncer.php
• normalizzazione della richiesta di modifica dei blocchi: app/Http/Requests/Admin/BlockRequest.php
• helper di persistenza: app/Support/Blocks/BlockPayloadWriter.php, app/Support/Blocks/BlockTranslationWriter.php, app/Support/Blocks/BlockTranslationResolver.php
• registro delle traduzioni: app/Support/Blocks/BlockTranslationRegistry.php
• form di amministrazione: resources/views/admin/blocks/types/*.blade.php
• renderer pubblici: resources/views/pages/partials/blocks/*.blade.php
• riferimenti di copertura: test su catalogo dei blocchi, rendering, traduzione e specifici per slug in tests/Feature/

Tipi di blocco core pubblicati attualmente documentati qui: 42.

La Fase 1 aggiunge un comando di audit sicuro per gli sviluppatori:

Il comando è in sola lettura.

• non modifica il database
• non dipende dal contenuto del sito installato
• legge le definizioni del catalogo core distribuito
• verifica la presenza dei file del form di amministrazione e del renderer pubblico distribuiti
• riporta i metadati della famiglia di traduzione e il supporto di base per i contenitori

Il comando è un supporto di aggiornamento per rilevare scostamenti di catalogo e di presenza dei file. Non sostituisce le note di contratto più complete contenute in questo documento.

La Fase 2 espone i dettagli del contratto in sola lettura in Admin -> System -> Block Types.

• ogni riga può aprire un modale Block Type Contract
• il modale è solo informativo e non invia aggiornamenti
• mostra i dettagli di catalogo, form di amministrazione, storage, traduzione, media o relazioni, figli, renderer e lacune a partire dal codice distribuito
• non trasforma l'amministrazione di Block Types in un editor di schemi o in un costruttore di form
• i tipi di blocco personalizzati o in bozza possono comunque aprire il modale, ma possono mostrare No shipped contract is documented for this block type yet. quando non è definito alcun contratto core

Attualmente i tipi di blocco pubblicati non hanno ciascuno una propria classe request dedicata.

• App\Http\Requests\Admin\BlockRequest è il percorso di richiesta di modifica condiviso
• i rami specifici per slug all'interno di quella richiesta normalizzano i campi verso l'archiviazione canonica attuale
• App\Support\Blocks\BlockPayloadWriter persiste il payload normalizzato del blocco
• App\Support\Blocks\BlockTranslationWriter sposta i campi di proprietà della lingua (locale) nelle righe di traduzione per le famiglie registrate
• App\Support\Blocks\BlockTranslationResolver risolve i valori tradotti o di fallback su un'istanza di blocco renderizzabile

Quel percorso di richiesta condiviso è una delle ragioni per cui la Fase 1 documenta prima i contratti, prima di qualsiasi lavoro di modifica basato su schema.

Lacune rilevanti ancora presenti dopo le correzioni attuali della Fase 3:

• gallery conserva ancora un percorso legacy di elementi di fallback basato sulle impostazioni quando le righe canoniche ordinate di block_media non sono presenti
• table — il suo renderer supporta ancora un percorso di fallback legacy basato su settings.rows anche se il modulo di amministrazione principale scrive il testo tradotto delle righe
• hero conserva ancora i fallback legacy dei campi quando i campi introduttivi tradotti canonici sono vuoti
• feature-grid e feature-item sono ora pubblicati perché supportati dal codice sorgente, ma restano intenzionalmente contratti delegati transitori sui percorsi di presentazione condivisi di Columns o Column Item
• tabs, slider, menu e faq-list esistono ancora come righe legacy del catalogo in stato di bozza, con moduli o renderer di compatibilità, ma non sono contratti core pubblicati e devono continuare a fallire in modo sicuro nella finestra modale del contratto e nell'output di audit
• showcase-list e contact-info esistono solo come percorsi di compatibilità per il rendering pubblico e non come blocchi pubblicati del catalogo core; i loro link basati sulle impostazioni seguono ora le stesse regole di URL pubblico sicuro degli altri renderer di blocchi
• i cataloghi pubblicati e in bozza coesistono, quindi qualsiasi futura esposizione in amministrazione deve distinguere esplicitamente tra contratti core pubblicati e righe in bozza o specifiche dell'installazione

Lavoro di standardizzazione consigliato in seguito per i gruppi di blocchi:

• definire gruppi di blocchi stabili di proprietà del prodotto, come layout, contenuto, navigazione, pattern e avanzato, in un'unica fonte di verità
• allineare i raggruppamenti del selettore, quelli della documentazione e quelli dell'amministrazione Block Types alla stessa fonte
• decidere quali blocchi attualmente in bozza o transitori debbano diventare supportati, archiviati o esplicitamente legacy
• standardizzare quali contratti siano supportati da traduzioni e quali siano intenzionalmente solo condivisi prima di iniziare qualsiasi lavoro sui moduli basati su schema

La Fase 1 stabilisce l'inventario attuale dei contratti pubblicati senza modificare il comportamento di modifica dei blocchi, la loro archiviazione o il rendering pubblico.

Quello era il punto di arresto previsto per il rilascio della Fase 1.

La Fase 2 rende visibile il contratto documentato nell'amministrazione Block Types come informazione di sola lettura, mantenendo invariati il comportamento di modifica dei blocchi, l'archiviazione, i renderer e il selettore.

La Fase 3 inizia a risolvere le lacune documentate a basso rischio nei contratti senza aggiungere un editor di schemi, un costruttore dinamico di moduli o un sistema di moduli di blocco basato su database.

• code ora segue il percorso di traduzione del testo esistente per titolo, etichetta e corpo dello snippet, mantenendo condiviso il linguaggio di sintassi
• table ora segue il percorso di traduzione del testo esistente per il titolo e il testo delle righe, mantenendo condiviso lo stile della tabella
• breadcrumb ora conserva al salvataggio le impostazioni condivise esposte
• stat-card ora utilizza l'URL opzionale esistente nel renderer pubblico con un link semplice e sicuro
• link-list ora esegue il rendering del testo introduttivo tradotto esistente sopra l'elenco degli elementi figli
• sticky-navbar ora allinea la proprietà persistita della radice della Navbar con Block::ownsPublicRoot() in modo che lo shell pubblico non aggiunga un wrapper generico aggiuntivo
• image ora segue il percorso di traduzione delle immagini esistente per la didascalia e il testo alternativo, mantenendo condivisi il media selezionato e l'URL del link opzionale
• gallery ora utilizza la tabella di proprietà della lingua (locale) block_gallery_item_translations per il testo alternativo, la didascalia, il titolo dell'overlay e il testo dell'overlay di ogni elemento, mantenendo condivisi i media ordinati della galleria e le impostazioni di presentazione, conservando gli elementi di fallback legacy per i contenuti vecchi ed escludendo il titolo e la descrizione legacy della galleria dalla modifica normale e dall'output pubblico
• download ora segue il percorso di traduzione del testo esistente per l'etichetta visibile e il testo di supporto, mantenendo condivisi il media selezionato e la variante del pulsante
• file, video e audio ora dispongono di moduli di amministrazione di prima classe e di normalizzazione delle richieste, così che il testo visibile tradotto e i media condivisi o le sorgenti URL compiano il round-trip attraverso lo stesso contratto con cui vengono già resi pubblicamente
• image, gallery, download, file, video e audio non accettano più il posizionamento arbitrario di nuovi figli e non eseguono più pubblicamente il rendering di alberi di figli storici arbitrari, mentre le righe figlie esistenti restano conservate negli alberi di blocchi dell'amministrazione
• code, table, quote, toc e html non accettano più il posizionamento normale di nuovi figli e non eseguono più pubblicamente il rendering di alberi di figli storici arbitrari, mentre le righe figlie esistenti restano conservate negli alberi di blocchi dell'amministrazione
• navbar-brand e sidebar-brand ora condividono un contratto conservativo di fallback basato sull'URL salvato o sulla home del sito, ed entrambi mantengono una denominazione accessibile e sicura per l'output con solo logo, senza imporre testo visibile
• sidebar-nav-group ora riutilizza la stessa semantica di output degli elementi manuali della barra laterale di sidebar-nav-item per i link figli annidati, mantenendo il contratto esistente del wrapper nav-group di WebBlocks UI
• section, container, grid, cluster, card e content_header ora usano la stessa fonte di contratto distribuita nel registro, nella finestra modale di contratto di sola lettura dell'amministrazione, nell'output di audit, nella documentazione e nella copertura di regressione mirata
• hero, columns, column_item, cta, feature-grid e feature-item sono ora pubblicati nel catalogo core distribuito, documentati nel registro dei contratti condiviso e coperti come contratti di marketing o di contenuto strutturato supportati dal codice sorgente, invece di restare solo in bozza o poco documentati
• le modifiche relative alla sola lingua (locale) per i pulsanti CTA gestiti e gli elementi figli strutturati ora conservano gli URL condivisi continuando ad aggiornare le etichette o il testo tradotti
• le primitive di layout mantengono le impostazioni di layout condivise e la struttura dei figli nell'archiviazione canonica dei blocchi, invece che in righe di traduzione o campi di testo arbitrari
• card ora utilizza un contratto di shell componibile: la Card padre possiede la radice wb-card, le regioni della Card possiedono wb-card-header, wb-card-body e wb-card-footer, i blocchi regione sono validi solo all'interno di Card e il testo Card salvato legacy viene conservato solo tramite un percorso di rendering di fallback minimo senza regioni
• content_header mantiene titolo, introduzione e testo meta tradotti, esegue sempre il rendering del titolo come H1, ignora in modo sicuro i valori legacy salvati del livello di intestazione e mantiene la sua radice semantica <header class="wb-content-header"> di proprietà del renderer, senza wrapper generico
• testimonial e stats restano documentati onestamente come comportamento di solo alias che delega ai percorsi di rendering esistenti di Quote o Columns, anziché come contratti core pubblicati autonomi
• tabs, slider, menu e faq-list restano slug in bozza o di compatibilità dell'era degli alias e non contratti core pubblicati, mentre showcase-list e contact-info restano renderer di compatibilità solo pubblici, senza una voce di contratto nel catalogo core distribuito