[BUG] Documentation: TypeScript in Custom Extensions section fails to compile

[mdickinson]

Software versions

Python version : 3.12.2 (main, Feb 10 2024, 11:36:40) [Clang 14.0.3 (clang-1403.0.22.14.1)]
IPython version : (not installed)
Tornado version : 6.4
Bokeh version : 3.3.4
BokehJS static path : /Users/mdickinson/Desktop/.venv/lib/python3.12/site-packages/bokeh/server/static
node.js version : v20.11.1
npm version : 10.2.4
jupyter_bokeh version : (not installed)
Operating system : macOS-13.6.4-x86_64-i386-64bit

Browser name and version

Not applicable

Jupyter notebook / Jupyter Lab version

Not applicable

Expected behavior

Steps to reproduce:

• Create a Python 3.12 venv, activate it, and do a pip install bokeh inside the activated environment.
• Starting from https://docs.bokeh.org/en/latest/docs/user_guide/advanced/extensions.html:
  • copy the TypeScript code from https://docs.bokeh.org/en/latest/docs/user_guide/advanced/extensions.html#javascript-models-and-views to a file custom.ts
  • copy the first Python snippet from https://docs.bokeh.org/en/latest/docs/user_guide/advanced/extensions.html#putting-it-together to a file custom.py
  • copy the second Python snippet from the same section to a file custom_extension.py
  • place all three files (custom.py, custom.ts, custom_extension.py) within an otherwise empty directory
• Edit the custom_extension.py file to add an import line: from custom import Custom
• From within the directory containing the three files above, execute bokeh serve custom_extension.py --show

Expected behaviour: an example web app is brought up in the browser that looks similar to the screenshot in the documentation.

Observed behavior

The server fails with a traceback:

(.venv) mdickinson@mirzakhani bokehbug % bokeh serve custom_extension.py --show 
2024-03-05 08:02:43,112 Starting Bokeh server version 3.3.4 (running on Tornado 6.4)
2024-03-05 08:02:43,117 User authentication hooks NOT provided (default user enabled)
2024-03-05 08:02:43,122 Bokeh app running at: http://localhost:5006/custom_extension
2024-03-05 08:02:43,122 Starting Bokeh server with process id: 11374
Compilation failed:

custom.ts:4:1 - error TS6133: 'p' is declared but its value is never read.

4 import * as p from "core/properties"
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
custom.ts:13:29 - error TS2339: Property 'slider' does not exist on type 'UIElement'.

13     this.connect(this.model.slider.change, () => {
                               ~~~~~~
custom.ts:32:22 - error TS2339: Property 'text' does not exist on type 'UIElement'.

32     }, `${this.model.text}: ${this.model.slider.value}`))
                        ~~~~
custom.ts:32:42 - error TS2339: Property 'slider' does not exist on type 'UIElement'.

32     }, `${this.model.text}: ${this.model.slider.value}`))
                                            ~~~~~~
custom.ts:56:17 - error TS2702: 'Custom' only refers to a type, but is being used as a namespace here.

56     this.define<Custom.Props>(({String, Ref}) => ({
                   ~~~~~~
custom.ts:56:33 - error TS7031: Binding element 'String' implicitly has an 'any' type.

56     this.define<Custom.Props>(({String, Ref}) => ({
                                   ~~~~~~
custom.ts:56:41 - error TS7031: Binding element 'Ref' implicitly has an 'any' type.

56     this.define<Custom.Props>(({String, Ref}) => ({
                                           ~~~
custom.ts:58:21 - error TS2304: Cannot find name 'Slider'.

58       slider: [ Ref(Slider) ],
                       ~~~~~~

Example code

# The `custom.py` file and `custom.ts` file are identical to those on the documentation page.
# Here's the modified `custom_extension.py` that I used.

from bokeh.layouts import column
from bokeh.models import Slider

from custom import Custom

slider = Slider(start=0, end=10, step=0.1, value=0, title="value")

custom = Custom(text="Special Slider Display", slider=slider)

layout = column(slider, custom)

Stack traceback or browser console output

The issue seems very similar to that raised in #9587 (long since closed). The documentation page referred to in that issue no longer exists, but the code in the new documentation appears to be derived from that code.

Apart from the TS compilation errors above, I think there's at least one other error that prevents the compiled extension from working correctly: the line static __name__ = "Surface3d" in the Custom class in the TypeScript code should read static __name__ = "Custom"

Screenshots

No response

[bryevdv]

It's possible the code block in the narrative docs has fallen out of sync with the actual (working) code that generated the working custom slider in the docs. That code is here:

https://github.com/bokeh/bokeh/blob/branch-3.3/examples/advanced/extensions/putting_together.py

I'll have to compare it when I get a chance.

[mattpap]

The code snippet in the docs is very outdated. The variant in examples/ directory is fine. It would be perfect if we could somehow avoid copying complex code between examples and docs, or perhaps have a way of compiling the contents of docs.

[bryevdv]

We have that, and it is used extensively in the docs, but it only works for single Python files. However there was a desire to split up this example in the narrative docs to provide more context to the different pieces, and suggest that things could be split across multiple files. I was going to suggest what you have done in he PR (split off the TS code and literalinclude it) as a possible compromise

[mdickinson]

Thanks for the fix; confirmed that the new 3.4.0 docs are working for me.