Jack Franklin
102df67838
A recent TS config change elsewhere had caused these tests not to compile with the error of: ``` error TS6307: File '/Users/jacktfranklin/src/devtools/devtools-frontend/scripts/component_bridges/value_for_type_node.ts' is not listed within the file list of project '/Users/jacktfranklin/src/devtools/devtools-frontend/test/unittests/scripts/component_bridges/tsconfig.json'. ``` The fix is to mark the dependency from the unit tests as a TS project reference, and then generate output in the same place as the source, so that import paths don't need to change. This isn't ideal, and we would use ts_library if doing this now, but this code pre-dates ts_library and also is only going to be around for the length of the TypeScriptification work, so it doesn't feel worth the effort to restructure it. Change-Id: I9a924bf3e2ed945dd22ce233eda2c8c15f3193c6 Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2466188 Reviewed-by: Tim van der Lippe <tvanderlippe@chromium.org> Commit-Queue: Tim van der Lippe <tvanderlippe@chromium.org> Auto-Submit: 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.