New component - Typescript/Javascript code - workflow?

Hi,
I am new to Bokeh and I enjoy it very much! But I want to extend Bokeh with a graphical widget of my own. I have seen the examples, but a few questions remain

  • Is there a reference for the Javascript/Typescript code to write? I can understand more or less from the examples what to do but I have not seen a documented API
  • The typescript file imports things from “core/properties” and “core/dom”… and my linter goes bonkers because it can’t find them (even if it works), what do you do when you write that file to make that a nice experience with your IDE?
  • How stable this API is supposed to be? What is the likelihood of my widget stopping to work after a software update?

Thanks!!

cc @mateusz

Hi @sharikone for a fairly long time BokehJS was a a hidden implementation detail, and only more recently become (somewhat) more user facing with the possibility of extensions, etc. But it still has not received as much attention, re: documentation, as the Python side has. This is actually a current topic of interest, so if you have experience or expertise you can share, please chime in on this dev discussion: Adopt JSDoc to document TypeScript code · Discussion #11309 · bokeh/bokeh · GitHub

Pretty much all the documentation there currently is on extending Bokeh is located in the user’s guide chapter:

Extending Bokeh — Bokeh 2.3.2 Documentation

BokehJS is still under active development, but I would not expect the property types in core/properties to change much, or the DOM helps in core/dom either. (But note that you don’t have to use core/dom at all, you could just create DOM objects manually)

and my linter goes bonkers because it can’t find them (even if it works), what do you do when you write that file to make that a nice experience with your IDE?

I don’t know the answer to this, perhaps @mateusz can chime in and then we can create an issue to document whatever the correct configuration is.

Thank you very very much!

You confirmed my impression that BokehJS is still lacking in its documentation.

I managed to get a satisfiable work environment (and to get linting: the secret is using the “paths” and “include” properties of tsconfig.json).

If you or @mateusz have a tip for creating a debugging environment too it would be wonderful and save me much time. As I see now the bokeh compiler produces a very big javascript bundle that includes all the modules, included the external ones, and includes it in the html file. If there was, say, a way to put breakpoints in the original typescript file that is fed to the compiler and use Chrome developer tools to debug the code it would really improve productivity. I am not nearly skilled enough in frontend development for coming up with a solution on my own, sadly.

Anyway, I am creating a graphic module to show quantum states in a Bloch sphere rendered using Three.js. If all goes well I will shamelessly showcase it here.

You confirmed my impression that BokehJS is still lacking in its documentation.

It is however, probably worth mentioning one caveat. Most of the work in Bokeh boils down to “setting property values on objects”. This is definitely true on the Python side, and still mostly true for CustomJS code. The Python and JS properties are maintained under test to be in complete agreement. In that sense, the existing reference guide for bokeh.models, although it is technically based on the Python codebase, is completely applicable to the JS side as well:

Every model and property listed there exists on both the Python and JS sides, with the same default values.

Now, all that said, things are a little more involved when discussing custom extensions, because that is the one area where there is more possibility of needing to use actual function/method APIs, and those are what are not documented especially well yet. But even there, I think the existing examples cover the a good chunk of common needs at least by way of demonstration (which methods might need to be defined, how to utilize screen mappers, etc).

If all goes well I will shamelessly showcase it here.

Looking forward to seeing it!