[META] Maintainable client-side data model + internal HTTP API

Overview

XB was originally developed in parallel:

• one pure client-side PoC
• one pure server-side PoC

Then we got the two talking to each other. XB was originally developed with support SDCs, exclusively, and this is still visible in the metadata about components (the /xb/api/config/component route's response): they're highly SDC-specific.

Then in December 2024, we overhauled it significantly in #3491013: Rework layout API to separate components and slots and introduced multiple "node types" in the JSON tree structure the client expects.

But virtually everything here has been demo-driven development. There's lots of loose ends, duplication, imprecise OpenAPI specs, etc.

Beta blockers (July 2025)

Beta blockers (tag: beta blocker) MUST happen before #3515932: Milestone 1.0.0-beta1: Enable creation of non-throwaway sites.

(Numbered lists must happen one after the other, bulleted lists can happen in parallel.)

• Permissions: #3452581: [META] XB Permissions
• Layout + model bugs and reliability:
  • ✅ #3520662: Empty slot not visible — client expects "slot node" for every *possible* slot, not for every *populated* slot
  • ✅ Missing "node type" in docs/data-model.md's 3.4 UI Data Model: communicating a `component tree` to the front end: a node type for exposed ContentTemplate slots: #3519352-32: Content templates, part 3b: store exposed slot subtrees on individual entities
• XB config entities bugs and reliability:
  • ✅ #3518808: XbConfigEntityHttpApiTest::testJavaScriptComponent test comments are incorrect regarding status updating
  • ✅ #3519634: Modifying a XB config entity's `status` or `label` should update the auto-save entry too, rather than delete it
• High-impact bugs
  • ✅ #3525130: Never show any messages in XB's previews

Stable blockers (October 2025)

Stable blockers (tag: stable blocker) do not block #3515932: Milestone 1.0.0-beta1: Enable creation of non-throwaway sites, but would be nice-to-have at that point in time. They MUST happen before #3517885: Milestone 1.0.0: Production Sites.

(Numbered lists must happen one after the other, bulleted lists can happen in parallel.)

• XB-eligible content entities functionality:
  • #3518292: Allow searching for content in the navigator, via `/xb/api/v0/content/{entity_type}`
• Finalize and de-SDC-ify component metadata (/xb/api/config/component):
  • ✅ #3504421: Rename `PropSourceComponent.field_data` to `.propSources`
  • ✅ #3515629: FieldWidget's XB transforms must be bubbled by the Field Widget rendering to inform the client
  • ✅ #3516705: Auto-saved changes to code components are not visible in preview-on-hover-component-list until published
  • #3510896: Add a new internal HTTP API for candidate `DynamicPropSource`s to enable a `ContentTemplate` UI
  • #3521041: [META] Refactor the organically grown Component metadata mess in PHP (`::getClientSideInfo()`) and JS (`BaseComponent`, `DynamicComponent`, `PropSourceComponent` etc.)
• Layout + model maintainability/completeness:
  • #3499632: Remove `ClientServerConversionTrait` (C→S) and `ComponentTreeItemList::getClientSideRepresentation()` (S→C) in favor of (de)normalizers
  • #3491701: [later phase] ApiLayoutController must use the previewed route's controller, and override canonical content entity routes' received entity object
  • #3510892: Allow XB to be gradually adopted: make XB's viewing (formatter) and editing (`ApiLayoutController::get()`) work with an empty XB field
  • Missing "node type" in docs/data-model.md's 3.4 UI Data Model: communicating a `component tree` to the front end: a node type for overrides/personalization variants Probably actually additional metadata on the existing nodeType: slot would be sufficient, for example mutuallyExclusive: true|false to indicate only one variant can be visible at a time, and perhaps some extra metadata for additional UI affordances Introduce nodeType: switch → PoC'd by @penyaskito at #3525565: Personalization ComponentSource PoC
• Back-end changes to improve front-end performance
  • #3505018: Return validation errors from LayoutController::post and ::patch
  • #3528847: Implement `lookup_keys` in Component for optimized queries
• OpenAPI/DX
  • ✅ #3471884: Rename all XB internal HTTP API routes from `/xb/api/…` to `/xb/api/v0/…`
  • #3472617: Document where the cut-off lies of where OpenAPI validation ends and entity validation begins
  • #3499809: Handle all paths in OpenAPI request validation
  • #3507427: /components/schemas/Component in openapi.yml is incomplete: add `source` and use it to make the OpenAPI spec more precise
  • #3541131: DX: Rename `ComponentInputsForm` to `ComponentInstanceForm`

Post-stable priorities (after October 2025)

Post-stable priorities (tag: post-stable priority) do not block any release, and are things we'd like to see happen, but are intentionally NOT happening any time soon. We're highly confident that these will be net additions without the need for backwards compatibility breaks.

None yet.