[DISCUSS] Goals and architecture of jupyter-ui-toolkit

[echarles]

@fcollonval thx for working on this.

I am linking here the work I am doing to create high level React.js components backed by the JupyterLab widgets: with jupyter-react https://github.com/datalayer/jupyter-react, you can add live notebooks, cells, terminals... in any React.js application. This can be used in existing solutions like e.g. Docusaurus or rich text editors like Slate or any custom user application. I have gathered an example repository to showcase such usages https://github.com/datalayer/jupyter-examples. If you want to know more on that, I am giving a talk at FOSDEM next Saturday (5th Feb 2022) https://fosdem.org/2022/schedule/event/lt_jupyter (online broadcasting).

It would be good to further discuss about the goals of this repository as well as the current technical choice. I dump here a few questions and reflexions and would love to further articulate and formalise in a document based on brainstorming with interested people:

• jupyter-ui-toolkit ships for now some low-level widget (like buttons, slider, select...) but does not provide any guidance on how to build on top of those. On one side, this is good as it allows supporting various technologies (react.js, vue...) but on the other side, there is a risk that developers create disparate and incompatible usage, resulting in frustration and fragmentation.
• To add behaviour, should a layer on top (react.js, vue.js...) or a layer below (core fast api a bit like https://lit.dev) be used? Anything would theorically work, but may practically not be ideal (see previous point).
• If the strategy to fork the vscode webview toolkit is kept, I wonder how to catch-up with the evolution (looking at https://github.com/microsoft/vscode-webview-ui-toolkit it looks to me they have already added a few widgets). Maybe a "composition" strategy could be discussed.
• At first sight, vscode-webview-ui-toolkit ships today a subset of other toolkits and is rather sparse. The advantage is that you can use it with react.js, vue.js... (strangely svelte is not listed, I guess it may be available one day). It has also some natural integration with VS-Code.
• About the adoption and approval of React.js in the broader Jupyter ecosystem, I can see arguments in favour, like jupyterlab already shipping a lot of widgets backed by react and JupyterHub shipping a react management ui (https://github.com/jupyterhub/jupyterhub/tree/main/jsx). Should this be discussed in some team governance levels to make it more official and further push in that direction?
• If we start building higher level components on top of any toolkit, another discussion could be started regarding a state management system to let those components communicate (RxJS is mentioned in Lumino v2 Plan jupyterlab/lumino#233, but that does not cover all the needs to reuse those components efficiently).

[fcollonval]

Thanks for reaching out @echarles

I am linking here the work I am doing to create high level React.js components backed by the JupyterLab widgets: with jupyter-react https://github.com/datalayer/jupyter-react, you can add live notebooks, cells, terminals... in any React.js application. This can be used in existing solutions like e.g. Docusaurus or rich text editors like Slate or any custom user application. I have gathered an example repository to showcase such usages https://github.com/datalayer/jupyter-examples. If you want to know more on that, I am giving a talk at FOSDEM next Saturday (5th Feb 2022) https://fosdem.org/2022/schedule/event/lt_jupyter (online broadcasting).

Thanks for sharing the info.

It would be good to further discuss about the goals of this repository as well as the current technical choice. I dump here a few questions and reflexions and would love to further articulate and formalise in a document based on brainstorming with interested people:

* `jupyter-ui-toolkit` ships for now some low-level widget (like buttons, slider, select...) but does not provide any guidance on how to build on top of those. On one side, this is good as it allows supporting various technologies (react.js, vue...) but on the other side, there is a risk that developers create disparate and incompatible usage, resulting in frustration and fragmentation.

The idea behind this repository is to evaluate web components as a basic technology to be reuse across Jupyter projects that come with coherent theme, keyboard navigation (for advanced components such tabs panel) and backed with some accessibility coloring rules with the lesser opinionated technological constrains.

That said, I'm learning on the way. And very shortly I will use this package in other projects to challenge the technology and some attention point raised during the JupyterLab team meetings. I hope that I could then provide more documentation on good practices.
Regarding the fragmentation, even if we are acknowledging the use of React in core. I have seen JupyterLab issues from people using almost any frameworks (Vue, React, Svelte,...). So this will definitely add to the existing fragmentation. But my hope is that it will reduce it on the long run if the provided components are powerful and reliable.

* To add behaviour, should a layer on top (react.js, vue.js...) or a layer below (core fast api a bit like https://lit.dev) be used? Anything would theorically work, but may practically not be ideal (see previous point).

A behaviour layer seems mandatory to not code yet another framework from scratch. custom-elements as defined by the standard are not as convenient as syntax offer by react or vue. Hence the appearance of template engines like Lit or Fast. Having a layer closer to the DOM will ease reuse - this is the reason I pick a web component library.

* If the strategy to fork the vscode webview toolkit is kept, I wonder how to catch-up with the evolution (looking at https://github.com/microsoft/vscode-webview-ui-toolkit it looks to me they have already added a few widgets). Maybe a "composition" strategy could be discussed.

* At first sight, vscode-webview-ui-toolkit ships today a subset of other toolkits and is rather sparse. The advantage is that you can use it with react.js, vue.js... (strangely svelte is not listed, I guess it may be available one day). It has also some natural integration with VS-Code.

At first I indeed started with vscode-webview-ui-toolkit, but now I reach the point where it is better to build on top of the fundamental library @microsoft/fast-fundation and @microsoft/fast-components. The goal is actually the same as vscode-webview-ui-toolkit tuning the styles of the basic elements to fit a design system of our own. So this results in composing our styles with behaviours and html templates from the base packages.

* About the adoption and approval of React.js in the broader Jupyter ecosystem, I can see arguments in favour, like jupyterlab already shipping a lot of widgets backed by react and JupyterHub shipping a react management ui (https://github.com/jupyterhub/jupyterhub/tree/main/jsx). Should this be discussed in some team governance levels to make it more official and further push in that direction?

That indeed will be good if at the team level we could decide what should be the technologies to push forward in the ecosystem. The future Jupyter Software Committee Council would be a good place. But it is unlikely to be up and running in the short future. So seems that a JEP is the best official way for pushing such idea.

* If we start building higher level components on top of any toolkit, another discussion could be started regarding a state management system to let those components communicate (RxJS is mentioned in [Lumino v2 Plan jupyterlab/lumino#233](https://github.com/jupyterlab/lumino/issues/233), but that does not cover all the needs to reuse those components efficiently).

That is a important topic indeed although I'm lacking experience on that front. But I happily discuss that further. Although it is not necessary to couple it with starting a toolkit, it should definitely be considered when comparing components technologies and the ease to connect them to a state management system.

[echarles]

Thx for engaging on this discussion. I am looking the web-components in relation with React.js, and an alternative framework to Fast (https://www.fast.design) is Lit (https://lit.dev) which has the notion of Reactive controllers (https://lit.dev/docs/composition/controllers - not sure what is bring, and not sure if Fast has something similar).

[fcollonval]

Indeed I saw that feature in Lit too. I did not spend much time learning Lit neither. For what I got, the best parallel I can make is custom hook in React JS - aka adding behavior to a component without mixing like react-router hooks.

In Fast, they don't have such feature.

[fcollonval]

I found a confirmation in @lit-labs/react that the reactive controller is a mean similar to the hook mechanism in React.

[echarles]

Thx, I have integrated that info in the jep proposal datalayer/jupyter-ui@79e83a6

[echarles]

React experimental release now supports web components, see codesandbox examples which are pretty self-explanatory

• https://codesandbox.io/s/shy-tdd-8b4tq?file=/src/App.js
• https://codesandbox.io/s/adoring-breeze-jrewu?file=/package.json

To ease the migration, I wonder if this repo should simply rely on the experimental branch of react and drop the current react-components package.

On facebook/react#11347 (comment), @gaearon clearly mentions You can start using it right away in the @experimental channel, but whether it lands in @18 or gets deferred to another major release depends on the amount of real-world testing the @experimental build will receive from the community., so there is an obvious risk to be stuck with experimental for a longer time than expected.

Relying on the experimental for now would also allow to try out the performance improvement features planned for v18.

[fcollonval]

I quickly try to set it up. But I cannot use it in JupyterLab as the federation is pulling react v17.

So I think I will open a branch with a standalone react gallery in v18 experimental while continuing alignment of the components and the react-components packages as it is not yet certain it will be part of v18.

[echarles]

I quickly try to set it up. But I cannot use it in JupyterLab as the federation is pulling react v17.

For try outs, you can force react versions via resolutions, eg. https://github.com/datalayer/jupyter-react/blob/475ee0002214d7be9207e4ce6080ea6fb30f0a2d/package.json#L116-L167

So I think I will open a branch with a standalone react gallery in v18 experimental while continuing alignment of the components and the react-components packages as it is not yet certain it will be part of v18.

If this is not too much work, that will be useful.