As a Qiskit Developer, I need the UI shell component available via a custom CDN so that I can integrate it into my HTML project

[agebbie]

Background:

The unified top menu has been released on all the pages within Qiskit.org other than the documentation, the below will address the final blocker we have preventing this from getting released to the documentation pages.

Acceptance Criteria:

1. Need to set up a CDN in IBM cloud -> link to tutorial
2. Need to make UI shell component available via the CDN
3. Set up automatic deployment when to the CDN when changes are made in the web components (so that users of the component via the CDN can get the latest versions)
4. Document to users how to use the component via the CDN

Related open issues:

• [Web Components | Lit] Investigate upgrade to Lit 2.x carbon-design-system/carbon-for-ibm-dotcom#6361

Additional context

We are unable to use the existing third party CDN because it is incompatible with certain dependencies in the carbon component, this is a blocker for this open issue: Qiskit/qiskit_sphinx_theme#64

In order to have the unified navbar on the documentation page, this blocker needs to be addressed. Additionally, if we want to be able to use web components within the docs in the future, we will need components available via the CDN.

cc @javabster @abdonrd

[abdonrd]

As mentioned in the last sprint planning, creating a CDN (and maintaining!) takes time and effort that the development team cannot address in the short term.

We have tried to use a public CDN like: https://jspm.org

And it should work fine, but there is an issue:
We have carbon-web-components as a dependency. And they use Lit v1 (lit-html@1 & lit-element@2).
And we use Lit v2 (lit-html@2 & lit-element@3).

And the CDN doesn't seem to be able to resolve dependencies well, because it only use Lit v2. And then, the components from carbon-web-components don't work.

But the plan to update carbon-web-components to Lit v2 is for this quarter! 🎉

• [Communications]: Add information to the README about upcoming v2 release carbon-design-system/carbon-for-ibm-dotcom#9750
• [Web Components | Lit] Investigate upgrade to Lit 2.x carbon-design-system/carbon-for-ibm-dotcom#6361 (comment)

After that update, everything should work on the public CDN!

[abdonrd]

Meantime, I think the easiest way would be bundle the UI Shell component on our side (so we resolve the dependencies well) and add it manually to the docs site.

We have this branch that creates the bundle:
https://github.com/Qiskit/web-components/compare/ui-shell-bundle

So the docs site can import ui-shell-bundle/index.js and should work.

[javabster]

Hi @abdonrd, there are a few reasons I think we should consider the CDN route more:

1. The carbon-web-components haven't given us a concrete date for the release other than 'some point in Q4'. If we want to make real progress with documentation before the end of the year I don't think we can wait around for their release (also it's possible the issue could get bumped to a later release or the release date delayed, who knows 🤷‍♀️ )

2. the way the sphinx theme works is that we make changes to the theme, release the package to pypi, then every qiskit repo needs to pip install it to start using the latest version of the theme. So if we use the bundled file for the ui shell component then every time the ui shell component gets updated here we will have to update the bundle file in the sphinx theme repo, release it again and every qiskit team will need to bump their version of the theme package. This is a lot of overhead for many teams and will just aggravate the problem of there being a lack of consistent UI between qiskit.org and the other qiskit.org/documentation pages. It would be much much better if we didn't have to do this process and could just automatically update the component in qiskit.org/documentation when it gets updated here

[abdonrd]

Attached the PR following #172 (comment):

• Replace top-menu with qiskit-ui-shell qiskit_sphinx_theme#116

[abdonrd]

2. the way the sphinx theme works is that we make changes to the theme, release the package to pypi, then every qiskit repo needs to pip install it to start using the latest version of the theme. So if we use the bundled file for the ui shell component then every time the ui shell component gets updated here we will have to update the bundle file in the sphinx theme repo, release it again and every qiskit team will need to bump their version of the theme package. This is a lot of overhead for many teams and will just aggravate the problem of there being a lack of consistent UI between qiskit.org and the other qiskit.org/documentation pages. It would be much much better if we didn't have to do this process and could just automatically update the component in qiskit.org/documentation when it gets updated here

I think will be the same case... Because you still need to manage the versions.

Link example: https://generator.jspm.io/#U2NgYGBkLM3ULc5IzclhcCjMLM7OLNEvT03STc7PLcjPS80rKXYw0LPUM9KHqQIAgTBUfDQA

With this you are using @qiskit/[email protected].
When we have @qiskit/[email protected], you also need to update the script.

- <link rel="preload" href="{{ pathto('_static/js/qiskit-ui-shell.js', 1) }}" as="script" />
- <script type="module" src="{{ pathto('_static/js/qiskit-ui-shell.js', 1) }}"></script>
+ <script type="importmap">
+ {
+   "imports": {
+     "@qiskit/web-components/ui-shell": "https://ga.jspm.io/npm:@qiskit/[email protected]/components/ui-shell/index.js"
+   },
+   "scopes": {
+     "https://ga.jspm.io/": {
+       "@babel/runtime/helpers/esm/decorate": "https://ga.jspm.io/npm:@babel/[email protected]/helpers/esm/decorate.js",
+       "@babel/runtime/helpers/esm/defineProperty": "https://ga.jspm.io/npm:@babel/[email protected]/helpers/esm/defineProperty.js",
+       "@babel/runtime/helpers/esm/get": "https://ga.jspm.io/npm:@babel/[email protected]/helpers/esm/get.js",
+       "@babel/runtime/helpers/esm/getPrototypeOf": "https://ga.jspm.io/npm:@babel/[email protected]/helpers/esm/getPrototypeOf.js",
+       "@babel/runtime/helpers/esm/objectSpread2": "https://ga.jspm.io/npm:@babel/[email protected]/helpers/esm/objectSpread2.js",
+       "@lit/reactive-element": "https://ga.jspm.io/npm:@lit/[email protected]/reactive-element.js",
+       "@lit/reactive-element/decorators/": "https://ga.jspm.io/npm:@lit/[email protected]/decorators/",
+       "carbon-components/es/globals/js/misc/on": "https://ga.jspm.io/npm:[email protected]/es/globals/js/misc/on.js",
+       "carbon-components/es/globals/js/settings": "https://ga.jspm.io/npm:[email protected]/es/globals/js/settings.js",
+       "carbon-web-components/es/components/ui-shell/": "https://ga.jspm.io/npm:[email protected]/es/components/ui-shell/",
+       "lit": "https://ga.jspm.io/npm:[email protected]/index.js",
+       "lit-element": "https://ga.jspm.io/npm:[email protected]/lit-element.js",
+       "lit-element/lit-element.js": "https://ga.jspm.io/npm:[email protected]/lit-element.js",
+       "lit-html": "https://ga.jspm.io/npm:[email protected]/lit-html.js",
+       "lit-html/directives/class-map": "https://ga.jspm.io/npm:[email protected]/directives/class-map.js",
+       "lit-html/directives/if-defined": "https://ga.jspm.io/npm:[email protected]/directives/if-defined.js",
+       "lit-html/": "https://ga.jspm.io/npm:[email protected]/",
+       "lit/": "https://ga.jspm.io/npm:[email protected]/",
+       "tslib": "https://ga.jspm.io/npm:[email protected]/modules/index.js"
+     },
+     "https://ga.jspm.io/npm:[email protected]/": {
+       "lit-html": "https://ga.jspm.io/npm:[email protected]/lit-html.js"
+     },
+     "https://ga.jspm.io/npm:[email protected]/": {
+       "lit-html": "https://ga.jspm.io/npm:[email protected]/lit-html.js"
+     }
+   }
+ }
+ </script>
+ 
+ <!-- ES Module Shims: Import maps polyfill for modules browsers without import maps support (all except Chrome 89+) -->
+ <script async src="https://ga.jspm.io/npm:[email protected]/dist/es-module-shims.js" crossorigin="anonymous"></script>
+ 
+ <script type="module">
+   import '@qiskit/web-components/ui-shell';
+ </script>

[abdonrd]

Maybe @Qiskit/qiskit-digital-devs want to give their opinions?

[abdonrd]

Meanwhile we also bundled the ui-shell before publishing to npm:

• Add experimental-bundled-ui-shell to the release #177

So we can replace the local import with a CDN: Qiskit/qiskit_sphinx_theme@37de726