Jack Franklin
d3f547209d
This CL introduces a script to generate `_bridges.js` files for TypeScript web components. For further details see: * `scripts/component_bridges/README.md` in this CL. * Modernising UI components: https://docs.google.com/document/d/1Asq9BDFFvnsqhDbpu2Ez92pugPN2-8nq50O6sNO0SpY/edit * Building bridges to a TypeScript world: https://docs.google.com/document/d/1qpa5QSSHrvvo_w73GV0hOJRug4N0_9JfFDw01d-NaCE/edit#heading=h.7nki9mck5t64 Change-Id: I95656acd6d22f5e09d178875dd3bcaf47da75a9c Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2108761 Reviewed-by: Paul Lewis <aerotwist@chromium.org> Reviewed-by: Tim van der Lippe <tvanderlippe@chromium.org> Commit-Queue: Jack Franklin <jacktfranklin@chromium.org>
Component bridges generation
We're building our web components in TypeScript but have to ensure that our legacy Closure code is happy and type-checks. See Building bridges to a TypeScript world for more details.
If you'd like to generate a bridge for a given component, run:
npm run generate-bridge-file ./front_end/path/to/component.ts
This will generate ./front_end/path/to/component_bridge.js.
Do not modify this by hand!.
If you change any types in component.ts, you should rerun this command (this will soon be enforced in a PRESUBMIT check).
## Details on the bridge
The bridges contain:
- Any interfaces that are needed in Closure code. These are taken from the TypeScript source and converted as a
@typedefthat Closure can understand. - A class definition for the custom element in the form of
class X extends HTMLElement. We use this class definition as a type in Closure land. - Any public methods defined in the component complete with JSDoc comments. Note that the function body is left empty.
- A function named
createX, whereXis the name of the component, that callsdocument.createElement('...').
## Debugging the bridges generation
The bridges code parses the component file to a TypeScript AST and walks through it looking for the particular parts of the code that are required.
The walking is done in walk_tree.ts which generates a state object which gets passed into generate_closure.ts which spits out JavaScript with JSDocs.
value_for_type_node.ts is able to take a single TypeScript node and convert it to the equivalent in Closure and this is used when generating interface definitions and JSDoc parameter comments.
You'll also find a suite of tests for this code in test/unittests/scripts/component_bridges.
These are not run on CQ but please use them locally when making a change to the generation. You can run them with:
npm run generate-bridges-test
It's important to note that the bridge generation code is not exhaustive; there are various TypeScript types that it does not yet support or understand. Rather than implement support for every node we're incrementally adding support as we need it. You should get a loud error message explaining that you're using an unsupported type. Feel free to make a CL to add support and if you'd like help reach out to one of the OWNERS.