[Meta] Plan for code components

In a Slack conversation about terminology between @effulgentia, @lauriii, @wim leers and myself, we decided the technical term we'll use for the new component source type is in-browser code components.

The "in-browser" prefix will be omitted in user-facing language and whenever the context is clear.

#6++ — I think all that is worth capturing in docs/ 😊🤓 Perhaps in docs/components.md?

#7++ 🌱 [Meta] Plan for code components Active — I created 📌 [PP-5] Documentation for code components Postponed . I suggest we wait with it until we tackle at least the issues I listed as blockers, so we have the full picture to write better docs. Until then, a brief explanation of the terminology is in the issue summary.

A new challenge apepared: https://git.drupalcode.org/project/experience_builder/-/merge_requests/5... for ✨ Create a ComponentSource plugin for JS components Active .

Remember that the way XB's UI is able to determine which parts of the (server-side rendered!) preview markup correspond to which components and slots is powered by HTML comments. Quoting /ui/tests/unit/function-utils.cy.js, it looks like this:

 <!-- xb-start-ad3eff8e-2180-4be1-a60f-df3f2c5ac393 --><div data-component-id="experience_builder:two_column" data-xb-uuid="ad3eff8e-2180-4be1-a60f-df3f2c5ac393">
          <div class="column-one width-25" data-xb-slot-id="ad3eff8e-2180-4be1-a60f-df3f2c5ac393/column_one">
            <!-- xb-slot-start-ad3eff8e-2180-4be1-a60f-df3f2c5ac393/column_one --><!-- xb-start-9bee944d-a92d-42b9-a0ae-abae0080cdfa --><h1 data-component-id="experience_builder:heading" class="primary" data-xb-uuid="9bee944d-a92d-42b9-a0ae-abae0080cdfa">A heading element</h1>
<!-- xb-end-9bee944d-a92d-42b9-a0ae-abae0080cdfa --><!-- xb-slot-end-ad3eff8e-2180-4be1-a60f-df3f2c5ac393/column_one -->
        </div>

          <div class="column-two width-75" data-xb-slot-id="ad3eff8e-2180-4be1-a60f-df3f2c5ac393/column_two">
            <!-- xb-slot-start-ad3eff8e-2180-4be1-a60f-df3f2c5ac393/column_two --><p>This is column 2 content</p><!-- xb-slot-end-ad3eff8e-2180-4be1-a60f-df3f2c5ac393/column_two -->
        </div>
    </div>
<!-- xb-end-ad3eff8e-2180-4be1-a60f-df3f2c5ac393 -->

(Note the xb-start- and xb-slot-start-.)

And like this:

                            <!-- xb-start-fce5e0e3-175f-48b5-a62c-176dbc5f3e91 -->
                            <div data-component-id="experience_builder:my-hero"
                                 class="my-hero__container">
                                <h1 class="my-hero__heading">
                                    <!-- xb-prop-start-fce5e0e3-175f-48b5-a62c-176dbc5f3e91/heading -->
                                    There goes my hero
                                    <!-- xb-prop-end-fce5e0e3-175f-48b5-a62c-176dbc5f3e91/heading --></h1>

(Note the xb-start- and xb-prop-start-.)

While editing components and placing them in slots requires only the annotations from the first kind (component + slot), SDC-sourced XB components actually already have their props annotated too, which will enable us to provide (visual and otherwise) affordances connecting inputs in the ComponentInputsForm form to very specific bits of markup in the preview. We're just not doing that yet. That work landed in preparation for 📌 Implement endpoint for realtime preview Active .
Because it's not yet actively used in XB, I explicitly +1'd not holding up #3498889 for that.

@larowlan pointed out in https://git.drupalcode.org/project/experience_builder/-/merge_requests/5... that we can keep generating xb-start- and xb-slot-start- HTML comments, but that xb-prop-start- is not actually possible. How did the folks working on the PoC envision supporting that?

AFAICT the closest issue to that 👆 is ✨ Editing components sourced as code components Active . But I figured I'd post on the meta/plan issue to avoid potentially derailing/blurring the scopes of #3500081. 😊

Adding ✨ Create a breadcrumb menu for code and component in the navigation bar Active to the must have list, after discussing with @balintbrews

xb-prop-start- is not actually possible

Not in scope for 0.3, but if we want to support this at some point, I think we'd need to do it as part of the source_js -> compiled_js compilation. For example, perhaps prior to compiling with SWC, we first pass the source JS through Babylon to find where props are being output and inject the HTML comments into there.

xb-prop-start- is not actually possible

My understanding is that this was added to support a future state where we didn't need a round trip to the server to update the preview.

With code components, we don't do any server side rendering so I don't think we need to worry about props - we will already have client side updates right?

My understanding is that this was added to support a future state where we didn't need a round trip to the server to update the preview.

In addition to that, wouldn't it be our way to support in-place editing further down the line?

With code components, we don't do any server side rendering so I don't think we need to worry about props - we will already have client side updates right?

In the initial implementation, prop values will be passed to the <astro-island> tag in a props attribute as JSON-encoded data. This markup is rendered in ✨ Create a ComponentSource plugin for JS components Active , so it's server-side . That attribute would be quite simple to update client-side, but we haven't made any plans to do so yet.

Yes to #13 but in addition there's also the desired future state where if, for example you click within the canvas on the part of the component where a prop is rendered, the ComponentInputsForm opens with focus on the corresponding widget.

Thanks, both of those make sense. I forgot about in place editing 👍️

adding a space just to update the issue summary issue statuses since we finished a sprint, is that how it's done?

Incredible progress the past 2 weeks! 🤩 Tested what landed last night, and found 2 problems, the first of which is definitely minor:

• 📌 Re-GETting the list is unnecessary: faster client, less server load Active
• 📌 Add (validation) error handling to AddCodeComponentDialog and friends Active

I think the first one is a NICE-TO-HAVE, the second one a MUST-HAVE.

I just updated the terminology again (s/in-browser/JavaScript) after @lauriii pointed out a while back that we can't call these components "in-browser", because we're planning to support creating them also via a CLI tool.

📌 Code Components should render with their auto-saved state(if any) when rendered in the XB UI Active is missing from the issue summary. Is that intentional?

It also doesn't account for the fact that auto-saves are not guaranteed to be in a working state. Which means that once 📌 Code Components should render with their auto-saved state(if any) when rendered in the XB UI Active is done, a temporarily broken code component could break all XB previews.

(For example: modifying the code to not output a slot, while the metadata does say that that slot exists.)

#20 🌱 [Meta] Plan for code components Active : I didn't update the issue summary with the issues that expanded those in the main story map, especially with auto-save related work where we had many unknowns. I'm happy to add that issue if it deserves to be on the main story map.

Can you please give more examples of how things can be broken?

For example: modifying the code to not output a slot, while the metadata does say that that slot exists.

How would this break? Wouldn't it just not output the slot?

How would this break? Wouldn't it just not output the slot?

Yes. And if 90% of the component tree happens to be in that slot, the result will be that suddenly all XB previews seem to be very broken because the majority of the content would be missing 😭😄

A different kind of breakage would be: the JS throws an error early on, causing it to not render anything at all. That might result in JS components having the same breakage as seen in the screenshot at 📌 Improve server-side error handling Active , but there we know we can prevent that from ever happening for SDCs — we just haven't done it yet.

The breakage in 📌 Improve server-side error handling Active is due to invalid component inputs, which can happen for any component type. The concern I'm raising in #20 and here is that for auto-saved code components there is a completely new failure mode: invalid component logic. And 📌 Code Components should render with their auto-saved state(if any) when rendered in the XB UI Active would cause that problem to instantly "spread" to all places where that code component is being used! 🧟

Added 📌 Add access control for "code components" and "asset libraries", special case: instantiated code components must be accessible to *all* Active .

Shouldn't ✨ Code Components as Block Overrides, step 1 Active be in here too?

Reflecting that … ALL MUST-HAVES ARE DONE! 🤯🥳

@lauriii and I realized an hour ago that we need a code component sibling of 📌 Implement endpoint for realtime preview Active .

@mayur-sose created 🐛 Creating multiple components with same label causes error: entity with ID already exists Active , which is a subset of 📌 Add (validation) error handling to AddCodeComponentDialog and friends Active .

With 🌱 [Plan] First-party code component imports Active being the next important feature for in-browser code components … @balintbrews can we close this? 🤞

Re #26, I opened ✨ Real-time preview for props changes of JS components Active .

Re #28, this issue still has child issues for CLI tooling, but maybe we should open a new Meta/Plan issue for that and move those to there? Especially since this issue even has "in-browser" in its title :)

maybe we should open a new Meta/Plan issue for that and move those to there? Especially since this issue even has "in-browser" in its title :)

💯 This! 😄