Delivery of Spectrum Web Components on Milo

[yesil]

TLDR; this post proposes a way to consume Spectrum Web Components on Milo with focus put on the performance.
This is only for SPA pages and regular Milo pages will not be affected by this proposal should it be implemented.
A POC is available, link at the bottom.

Overview

Spectrum Web Components (SWC) provides some advanced UI components that are not available in the Consonant Library OOTB on Milo.
e.g: Sidenav, Menu, Search, Popover, custom Modals, etc.

Current Catalog, Plans and TWP pages are depending on those components and Milo version will ship with them as well.

SWC documentation doesn't provide guidance on how to optimize the dependencies, expect for bundling them all together.

In order to follow Milo philosophy with SWC where a component is loaded only when it is needed, I propose the following approach:

1. Milo centralises SWC components delivery for the consumers
2. Milo provides OOTB, sp-theme with light medium scale configuration but is not limited to.
3. Each SWC component is bundled separately, e.g: /libs/features/spectrum-web-components/button.js
4. Milo block is responsible for importing swc components that are used as part of the block logic.
5. Milo block doesn't need to know about transitive dependencies, they will be resolved automatically.

Implementation

For each SWC component that we want to use, the developer adds a file (notice src in the path), e.g: /libs/features/spectrum-web-components/src/button.js
in which the necessarily imports and exports are added. Often it will be a single line file.

e.g:
button.js
import '@spectrum-web-components/button/sp-button.js';

Run npm run build at libs/features/spectrum-web-components, which generates small bundles containing individual swc components using esbuild.

Add a test file for this SWC component, and PR Milo.

Performance

By optimising the number of resources and web-components imported we can reduce the impact on LCP considerably.

Tests

Test files contains one or multiple spectrum components and nothing else.

1. sp-theme + sp-button
URL: https://mwpw-139915--milo--yesil.hlx.live/sp-base.html
Resources: 4 files
Overhead: 60.9kb gzip
LH score: 100 (https://pagespeed.web.dev/analysis/https-mwpw-139915--milo--yesil-hlx-live-sp-base-html/mwvpubznb1?form_factor=mobile)

2 .theme + button + overlay + menu + popover + dialog
URL: https://mwpw-139915--milo--yesil.hlx.live/sp-build.html
Resources: 15 files
Overhead: 172kb gzip
LH score: 100 (https://pagespeed.web.dev/analysis/https-mwpw-139915--milo--yesil-hlx-live-sp-build-html/kfxgyro100?form_factor=mobile)

Catalog page(WIP):

https://mwpw-139915--cc--yesil.hlx.live/drafts/ilyas/catalog?milolibs=mwpw-139915-catalog--milo--yesil&martech=off#category=all

Source codes: https://github.com/adobecom/milo/compare/main...yesil:MWPW-139915?expand=1

[npeltier]

thanks @yesil, sounds reasonable to me

[mokimo]

I think it's a cool idea to have a common way of consuming Spectrum Web Components opt-in in a common fashion.
Milo could provide some optional util functions for consumers that specifically want/require Spectrum Web Components.

[Westbrook]

Great start to the conversation here. Exciting to see this moving in a direction that can be productive for various teams. Some areas of thought/questions to keep in mind as things continue to come together here...

Is Milo consumption really served by a single theme configuration?
If so, it may be useful to investigate delivering theme data (CSS custom properties) with CSS rather than via the <sp-theme> element. For instance, the example here uses color="light" and scale="medium" if that was the case 100% of the time, the CSS for the same is:

  @import url('@spectrum-web-components/styles/core-global.css');
  @import url('@spectrum-web-components/styles/tokens/global-vars.css');
  @import url('@spectrum-web-components/styles/tokens/spectrum/global-vars.css');
  @import url('@spectrum-web-components/styles/tokens/spectrum/custom-vars.css');
  @import url('@spectrum-web-components/styles/typography.css');
  
  :host {
      display: block;
  }
  
  #scale,
  #theme {
      width: 100%;
      height: 100%;
  }
  
  @import url('@spectrum-web-components/styles/theme-light.css');
  @import url('@spectrum-web-components/styles/tokens/light-vars.css');
  @import url('@spectrum-web-components/styles/tokens/spectrum/custom-light-vars.css');
  @import url('@spectrum-web-components/styles/scale-medium.css');
  @import url('@spectrum-web-components/styles/tokens/medium-vars.css');
  @import url('@spectrum-web-components/styles/tokens/spectrum/custom-medium-vars.css');
  @import url('@spectrum-web-components/styles/tokens/spectrum/medium-vars.css');

This could also be pre-built/bundled into libs assets as shown in your PR and possibly save additional download/parse/compile time in a page load. Further nuance can even be achieved with appropriate consumption of media queries to get light/dark and mobile/desktop bifurcation a la https://github.com/adobe/spectrum-web-components/blob/main/projects/documentation/src/components/styles.css

Does a practice here deserve a version management policy?
Once something like this is available, teams will want to use it. When they do, they'll want to receive fixes to bugs they find or features added when their requests are new to the scope of the patterns supported. How would an approach like this serve the various users that fall within this segment? For reference, SWC tends to make roughly bi-weekly (every two weeks) releases of their library with fixes/features.

**Relation between "source" files and "output" files?"
How does libs/features/spectrum-web-components/src/button.js relate to libs/features/spectrum-web-components/button.js? How is that relationship maintained?

Is it practical to attempt to normalize consumption patterns to reduce the need to additional documentation?
Currently, the demo consumes URLs like <script src="./libs/features/spectrum-web-components/button.js" type="module"></script>, these are unique to the Milo contexts and would likely benefit from clear documentation, allowing a user to fully understand what they are consuming in that case. Would leveraging something like import maps allow for a consumption patterns that looked more like the SWC documentation today <script src="@spectrum-web-components/button/sp-button.js" type="module"></script> while still latching onto the patterns you're outlining?

Multiple registrations of the same name issues
While strict adherence to this pattern would likely ensure that multiple registrations of the same name errors would not be encountered, registering names into the global registry open the door to possibly encountering this situation. In what ways could/should this pattern prepare for this?

[yesil]

Thanks @Westbrook for your valuable inputs.
Once I digest them all I'll update here :)

[yesil]

Is Milo consumption really served by a single theme configuration?

On Milo the default theme is light, but the dark theme is supported in different blocks.

Combining styles into a separate CSS file seems to increase the bundling complexity.
Is this strongly recommended?

Does a practice here deserve a version management policy?

My idea was to add a test file for each SWC component so that whenever we bumpe the SWC version, if the tests are green, we can assume that it is good to go.
Thus, we can always deliver the same SWC version to all consumers.

I would like to avoid a situation where a Milo block depends on sp-textfield v40 and another one depends on sp-textfield v42, which is not possible in the same page.

**Relation between "source" files and "output" files?"

src file is where we add imports/exports we need from SWC.
I actually changed the dest folder, and now it is libs/features/spectrum-web-components/dist. As the name suggest, everything under suggest is generated automatically by Esbuild.

importmaps

Regarding importmaps, we don't want to force downstream Milo consumers to add/maintain static importmaps if they are not using them in a page(they have own head.html)
Adding importmaps via javascript is an option but the browser support is not good enough, AFAIK Milo should work with Safari 14.x.
https://caniuse.com/mdn-html_elements_script_type_importmap

Multiple registrations of the same name issues
From what I have seen, SWC are protected against multiple registration.

On Milo, the eng team will be responsible for enabling SWC on pages, so I don't expect any conflict as long as we import dependencies from the same location.

[chrischrischris]

EDIT: I did not see

This is only for SPA pages and regular Milo pages will not be affected by this proposal

so these comments don't apply (as much).

--- OG comment --

Using spectrum web components would definitely increase developer productivity and prevent us from re-creating components.

However, I think we should approach this very carefully. @yesil in your demos you show a lighthouse score of 100, but those are very simple non-real-world examples.

The spectrum button by itself takes 60k. The current equivalent button in milo is apx 5k.

Also by bundling everything for each component, all shared swc code is repeated in each file.

I think that there may be some use cases for this:

• Author tools where perf is not a concern
• Complex ui elements that would require too much time to create ourselves

Then again - even if it's not in Milo there's nothing stopping consumers from doing it for their project, as long as they recognize the potential overhead they are adding to the page.

[yesil]

@chrischrischris you having worked on Plans page more than anyone in the team, you can guess the UI is too complex to create with vanilla JS/CSS.
So this only applies for UI heavy pages.

[Axelcureno]

Since using Spectrum comes with its own styles, what would happen in a scenario where Consonant styles differ from Spectrum's? What is the level of flexibility that Spectrum provides for on-demand changes like this?

[yesil]

AFAIK, the only overlap is the button component and from what I checked, they look the same.
Typically, the card CTAs in the catalog page will be consonant button whereas the sidenav, custom modal(filters on mobile) will be spectrum.

[npeltier]

Can we rather proceed to some tests with catalog pages @yesil? Obviously for admin/authoring purpose i think it's a great deal. But usage makes me think that yes our complex UI pages should probably use it. And yes, if it's just for a button, it's definitely not worth bringing it in.

[npeltier]

about commons files duplication, that's a good point, and i'd be curious to see what is the part of it in a real use case like this

[yesil]

Normally there should not be common file duplication, that is the goal in this PR.

[yesil]

I'll create a new branch for testing catalog with this approach.

[yesil]

Test URL: https://mwpw-139915--cc--yesil.hlx.page/drafts/ilyas/catalog?milolibs=mwpw-139915-catalog--milo--yesil&martech=off&georouting=off

[auniverseaway]

I think this is a merch / plans area of concern and should be scoped as such. Milo shipping this as a generic solution implies we agree with the performance characteristics of SWC and we do not.

Your "samples" are myopic and limited and do not accurately reflect the realities we operate in. From what I can see, none of your samples use any real-world blocks or milo in general. We can make bare pages all day long with React and call them performant, too.

You are saying that a 60KB dependency to put a button on a page is performant? In Franklin land we typically say if you can get to LCP within 100KB, you should be OK as long as you don't ship any TBT. A single button here is 60% of that budget. The heart of milo (utils.js) is 11KB last I checked. If you have a 50KB LCP image plus this button, you're done... you're not going to be 100. That's not even including the page HTML, scripts.js, styles.css, or even Milo utils.

Never would I say taking up 60% of a site's LCP budget for a single button is considered performant. I wouldn't base that opinion on your samples above, either.

I think getting some better real world examples together that accurately reflect our realities and proving the case that a 60KB dependency for a single button is still going to net us 100LH would be a better use of everyone's time. And the samples should have these dependencies in LCP. They should not hide behind existing vanilla blocks.

I also fail to see what this is actually buying you. We know from Dexter putting a dependency on Spectrum means we are no longer in control of behaviors. When they decide to zig when we need them to zag, we are at a disadvantage. I think there's a lot of accessibility wins to gain from SWC, but I don't think that is enough to warrant the significant overhead you're asking for. The question I always have is, "What happens first? Consonant / Milo buttons become as accessible as Spectrum or Spectrum ships performant components?" I don't envy the place they are in with a significant codebase and a lot of dependencies, but that's the reality we live in. Getting a performant version of Spectrum seems to be a long way off.

I advocated before that vanilla merch cards that do not have high interactivity and state requirements do not need these types of dependencies and the commerce team still insisted on making everything a Web Component. So now, just to get a single card on a page, you need at the very least a 10KB Lit dependency. The list of anti-patterns here is numerous. I've stayed out of the way here as it relates to merch / commerce and will continue to do so. If you want to ship a 60KB button, go for it, but as the owner of Milo I won't bless this as some sort of supported pattern because I fundamentally do not agree with it.

[yesil]

I'd like to clarify a couple of points about the proposal.

Firstly, merch-card block doesn't and will not use SWC button, we use Milo's Consonant Button to keep the vanilla cards simple.
Compared to initial implementation with CaaS, we reduced the size by 7kb(gzip) with Lit included.

The proposal mainly targets SPA feature-rich pages like Plans, Catalog and not the regular content pages.
Typically those pages do have several components than just a button.
The button example above was shared to provide the baseline cost of SWC, and not to advertise how performant it is.

I noticed in your response that some aspects of the overall context might not have been fully considered.
With this proposal, we wanted to provide a relatively manageable solution for the SPAs being built upon Milo.
Today Milo doesn't provide the capabilities to build a fully fledged SPA page, and I'm not sure whether it is in the roadmap.

If you have ideas or recommendations other than "don't use this", I'm all ears.

[auniverseaway]

With this proposal, we wanted to provide a relatively manageable solution for the SPAs being built upon Milo.

All of our SPA needs thus far have been A) author facing, or B) contributed by another team (CaaS).

For (A) Milo provides some UI controls that anyone can use. These have been used fairly extensively in our configurators. As the primary person who has built other SPAs on Milo, I haven't found a ton of value in most of the controls beyond the configurator use case. I think we're still early in understanding what we want our authoring experiences to be.

I noticed in your response that some aspects of the overall context might not have been fully considered.

I think I have fully considered your proposal. As someone who is maybe your ideal customer, I'll pass on the offer to use SWCs in Milo. I don't think we (Milo) should willingly take on a 3rd party dependency that we know has performance issues. Not only this, but you're asking us to accept a solution we don't currently have a need for. You're also asking us to put an arbitrary build step in whenever there are changes or updates required. I think your commerce use cases are a different story...

If you have ideas or recommendations other than "don't use this", I'm all ears.

I think using whatever you want for commerce is 100% fine. Do whatever helps you be successful. If that's bits of SWC, great. If that's WCs, great. If that's vanilla JS, that's great, too. I have long advocated that if it walks and talks like an SPA, you should build it like an SPA. You may not get our approvals, but we're also not going to request changes on your PR. UAR, CaaS, etc. all have or had performance problems and we didn't block those PRs.

---

My recommendation is still the same as it has been for almost two years now:

1. If it's not 100, it shouldn't ship.
2. Only make an SPA if you truly need an SPA.
3. If you have to compromise on performance, be very transparent why.
4. Don't ship anything generic before you've used something 5 times.

[yesil]

Don't ship anything generic before you've used something 5 times.

We are already building Catalog page, TWP and Buy Now Modals.
Individual, Business and Education plans pages are next.
This is why we wanted to make it re-usable.

If you have to compromise on performance, be very transparent why.

All the above pages are lift-and-shift efforts with small changes and not redesigns from scratch where existing UI/UX could be questioned.
Therefore they have been estimated as such.

Closing the thread, thanks for your feedback.