Block Type Contracts

This document began as the Phase 1 inventory of the currently shipped published core block types in WebBlocks CMS, now also documents the Phase 2 read-only admin contract view, and records the Phase 3 gap-standardization fixes completed so far, including the Layout + Card cleanup for section, container, grid, cluster, card, and content_header, the Marketing / Structured Content cleanup for hero, columns, column_item, cta, feature-grid, and feature-item, and the Legacy / Transitional cleanup that keeps old compatibility slugs documented honestly without promoting them into the published core catalog.

Phase 1 is read-only documentation only.

• It does not redesign block forms.
• It does not add a DB-driven form builder.
• It does not migrate block content.
• It does not change public rendering.
• It does not change how Admin -> System -> Block Types edits work today.

The current Block Types admin screen remains a catalog and metadata screen. In Phase 2 it can now open a read-only Contract modal for each listed row, but it is still not a dynamic form builder or schema editor.

Plugin Phase 3 adds declaration-only plugin block hooks through PluginBlockTypeDefinition, PluginBlockPackDefinition, and PluginBlockRegistry. Enabled plugins can expose plugin-owned handles such as analytics-tools::score-card for discovery, but these declarations do not replace the shipped core block contracts, core block views, core seeders, or block editing services. Unqualified core-style handles such as hero remain core-owned and are rejected for plugin declarations.

A Block Type Contract is the current technical agreement for how one block type behaves across CMS layers:

• catalog identity: slug, label, category, status, and system or container metadata
• admin form source: which Blade partial currently edits the block and which fields it exposes
• validation and request handling: how App\Http\Requests\Admin\BlockRequest currently normalizes and validates block payloads
• storage ownership: which values live on blocks, dedicated translation rows, block_media, or related records
• translation ownership: which user-facing fields are locale-owned
• shared ownership: which settings or relationships remain shared across locales
• media or relationship ownership: direct media_id, ordered block_media, navigation lookups, or same-page relationships
• child support: whether the block is a container and whether child types are restricted
• public renderer source: which public Blade partial renders the block today
• renderer root contract: whether the block owns its public root markup or relies on the generic wrapper path
• portability and revisions: whether the current storage shape should continue to travel through revisions, clone, export/import, and promotion
• tests and gaps: known focused coverage, unclear behavior, or compatibility debt

Status terms used below:

• clear: admin form, request handling, storage, and renderer mostly line up
• mostly clear: current contract is understandable but has one notable caveat
• transitional: current contract intentionally carries a compatibility path or mixed ownership pattern
• needs review: current code paths disagree or behavior is underdocumented enough that Phase 2 should surface it more clearly
• legacy/fallback: published behavior depends on a fallback or compatibility path

Current and future contract work should keep these ownership rules explicit:

• user-facing copy belongs in translation rows when the block is locale-owned
• shared operational or settings data belongs in shared block settings or explicit relationships
• media should use media_id or block_media ownership paths where applicable
• avoid moving user-facing content into arbitrary settings JSON
• keep compatibility storage paths documented when they still affect public output or imports

This Phase 1 inventory is based on the shipped source, not guesses.

• catalog source: app/Support/Blocks/CoreBlockTypeCatalogSyncer.php
• block edit request normalization: app/Http/Requests/Admin/BlockRequest.php
• persistence helpers: app/Support/Blocks/BlockPayloadWriter.php, app/Support/Blocks/BlockTranslationWriter.php, app/Support/Blocks/BlockTranslationResolver.php
• translation registry: app/Support/Blocks/BlockTranslationRegistry.php
• admin forms: resources/views/admin/blocks/types/*.blade.php
• public renderers: resources/views/pages/partials/blocks/*.blade.php
• coverage references: block catalog, rendering, translation, and slug-specific tests under tests/Feature/

Published core block types currently documented here: 42.

Phase 1 adds a safe developer audit command:

The command is read-only.

• it does not modify the database
• it does not depend on installed site content
• it reads the shipped core catalog definitions
• it verifies shipped admin form and public renderer file presence
• it reports translation-family metadata and basic container support

The command is a freshness aid for catalog and file-presence drift. It is not a substitute for the fuller contract notes in this document.

Phase 2 exposes contract details read-only in Admin -> System -> Block Types.

• each row can open a Block Type Contract modal
• the modal is informational only and does not submit updates
• it shows catalog, admin form, storage, translation, media or relationship, child, renderer, and gap details from shipped code
• it does not make Block Types admin a schema editor or form builder
• custom or draft block types can still open the modal, but may show No shipped contract is documented for this block type yet. when no core contract is defined

Published block types do not each have their own dedicated request class today.

• App\Http\Requests\Admin\BlockRequest is the shared edit request path
• slug-specific branches inside that request normalize fields into current canonical storage
• App\Support\Blocks\BlockPayloadWriter persists the normalized block payload
• App\Support\Blocks\BlockTranslationWriter moves locale-owned fields into translation rows for registered families
• App\Support\Blocks\BlockTranslationResolver resolves translated or fallback values back onto a renderable block instance

That shared request path is one reason Phase 1 documents contracts first before any schema-driven edit work.

Current remaining high-signal gaps after the current Phase 3 fixes:

• gallery still preserves a legacy settings-based fallback item path when canonical ordered block_media rows are missing
• table renderer still supports a legacy settings.rows fallback path even though the core admin form writes translated row copy
• hero still preserves legacy field fallbacks when canonical translated intro fields are empty
• feature-grid and feature-item are now published because they are source-backed, but they remain intentionally transitional delegate contracts over the shared Columns or Column Item presentation paths
• tabs, slider, menu, and faq-list still exist as legacy draft catalog rows with compatibility forms or renderers, but they are not published core contracts and should continue to fail safely in the contract modal and audit output
• showcase-list and contact-info still exist only as public-render compatibility paths rather than shipped published core catalog blocks; their settings-driven links now follow the same safe public URL rules as other block renderers
• published and draft catalogs coexist, so future admin surfacing must stay explicit about published core contracts versus draft or install-specific rows

Recommended later standardization work for block groups:

• define stable product-owned block groups such as layout, content, navigation, pattern, and advanced in one source of truth
• align picker groupings, docs groupings, and Block Types admin groupings to that same source
• decide which currently draft or transitional blocks should become supported, archived, or explicitly legacy
• standardize which contracts are translation-backed versus intentionally shared-only before any schema-driven form work starts

Phase 1 establishes the current published contract inventory without changing block editing behavior, block storage, or public rendering.

That was the intended stopping point for the Phase 1 release.

Phase 2 makes the documented contract visible in the Block Types admin as read-only information while keeping block edit behavior, storage, renderers, and picker behavior unchanged.

Phase 3 starts resolving low-risk documented contract gaps without adding a schema editor, dynamic form builder, or DB-driven block form system.

• code now follows the existing text-translation path for title, label, and snippet body while keeping syntax language shared
• table now follows the existing text-translation path for title and row copy while keeping table style shared
• breadcrumb now preserves the exposed shared settings on save
• stat-card now uses the existing optional URL in the public renderer with a simple safe link
• link-list now renders the existing translated intro copy above the child item list
• sticky-navbar now aligns persisted Navbar root ownership with Block::ownsPublicRoot() so the public shell does not add an extra generic wrapper
• image now follows the existing image-translation path for caption and alt text while keeping selected media and optional link URL shared
• gallery now uses locale-owned block_gallery_item_translations for per-item alt text, caption, overlay title, and overlay text while keeping ordered gallery media and presentation settings shared, preserving legacy fallback items for old content, and excluding legacy gallery title/description from normal editing and public output
• download now follows the existing text-translation path for visible label and helper copy while keeping selected media and button variant shared
• file, video, and audio now have first-class admin forms and request normalization so translated visible copy and shared media or URL sources round-trip through the same contract they already render publicly
• image, gallery, download, file, video, and audio no longer accept new arbitrary child placement and no longer render arbitrary historical child trees publicly, while existing child rows remain preserved in admin block trees
• code, table, quote, toc, and html no longer accept new normal child placement and no longer render arbitrary historical child trees publicly, while existing child rows remain preserved in admin block trees
• navbar-brand and sidebar-brand now share a conservative saved-URL or site-home fallback contract, and both preserve safe accessible naming for logo-only output without forcing visible text
• sidebar-nav-group now reuses the same manual sidebar item output semantics as sidebar-nav-item for nested child links while preserving the existing WebBlocks UI nav-group wrapper contract
• section, container, grid, cluster, card, and content_header now use the same shipped contract source across the registry, read-only admin contract modal, audit output, docs, and focused regression coverage
• hero, columns, column_item, cta, feature-grid, and feature-item are now published in the shipped core catalog, documented in the shared contract registry, and covered as source-backed marketing or structured content contracts instead of remaining draft-only or underdocumented
• locale-only edits for managed CTA buttons and structured child items now preserve shared URLs while still updating translated labels or copy
• layout primitives keep shared layout settings and child structure on canonical block storage instead of translation rows or arbitrary copy fields
• card now uses a composable shell contract: the parent Card owns the wb-card root, Card regions own wb-card-header, wb-card-body, and wb-card-footer, region blocks are only valid under Card, and legacy saved Card copy is preserved only through a minimal no-region fallback renderer path
• content_header keeps translated title, intro, and meta copy, always renders its title as H1, safely ignores legacy saved heading-level values, and keeps its semantic <header class="wb-content-header"> root renderer-owned without a generic wrapper
• testimonial and stats remain documented honestly as alias-only behavior that delegates to existing Quote or Columns render paths rather than as standalone published core contracts
• tabs, slider, menu, and faq-list remain draft or alias-era compatibility slugs rather than published core contracts, while showcase-list and contact-info remain public-only compatibility renderers with no shipped core contract entry