Webui Lit Migration

Chromium WebUI Lit Migration

Step 1: Run scripts/run_codemod_script.sh

IMPORTANT: Always do this first, as it automates trivial migration steps.

Run the script in this skill's scripts directory. Pass the path to the Polymer based element's TS class definition file as the parameter. Example: ./webui-lit-migration/scripts/run_codemod_script.sh
chrome/browser/resources/certificate_manager/certificate_entry.ts

Step 2: .ts file cleanup

1. Replace PolymerElement import The script replaces this import except in cases where multiple things are imported from Polymer. If an import from polymer_bundled.min.js is still present after running the script, remove it and add: import {CrLitElement} from '//resources/lit/v3_0/lit.rollup.js';

2. Update 'extends PolymerElement' The script will update this in the case that no mixins are used. If there is still a reference to PolymerElement: replace SomeMixin(PolymerElement) with SomeMixinLit(CrLitElement)

3. Address any "TODO: Port this observer to Lit" comments left by the migration script as follows: a. Examine the observer (e.g. 'onFooChanged_') method. If it does not reference the DOM, add the following in a willUpdate callback. If it does reference the DOM (e.g., this.shadowRoot or this.$), add this in a updated() lifecycle callback instead.

if (changedProperties.has('foo')) {
  this.onFooChanged_();
}

b. If the property being observed is protected or private, the
   changedProperties lifecycle method parameter will require a cast:

const changedPrivateProperties = changedProperties as Map<PropertyKey, unknown>;
if (changedPrivateProperties.has('myProperty_')) { ... }

c. Remove the added TODO and the commented out observer line.

4. Address any complex observers in a similar way. Look for an "observers: " line:

observers: ['onFooOrBarChanged_(foo, bar)']

Remove the line and for each observer listed, add to a lifecycle method as described for single property observers, but check changedProperties for any of the properties listed in the observer:

if (changedProperties.has('foo') || changedProperties.has('bar')) {
  this.onFooOrBarChanged_();
}

5. Move value initialization out of 'properties' to the declaration.

Replace

  foo: {
    type: String,
    value: 'foo',
  },
  ...
  value: string;

with

  foo: {
    type: String,
  },
  ...
  accessor value: string = 'foo';

For uninitialized properties, if a TS compiler error is thrown on build, initialize to a dummy or default value rather than using a non-null assertion operator or changing the type definition.

Step 3: Check for any missing shared CSS styles.

If any imported style file does not exist, check if the Polymer version (same file path, but without _lit suffix) exists. If so, generate the Lit version as follows:

1. Create Lit Version: Create [shared_style]_style_lit.css.
2. Copy Content: Copy the CSS rules to the new *_lit.css file.
3. Update Metadata: Use #type=style-lit in the metadata. Update any imported and included styles to the lit version (e.g. cr_shared_style.css.js import --> cr_shared_style_lit.css.js import, include="cr-shared-style" becomes include="cr-shared-style-lit").
4. Empty Original: Clear the original *_style.css file, leaving only its] metadata header and a comment:

   /* Purposefully empty since this style is generated at build time from the
    * equivalent Lit version. */

5. Import in Component: Component CSS should import the new *_lit.css.js and include it.
6. BUILD.gn: Add the new *_lit.css to css_files.

Step 4: Update .html.ts template file

1. Replace any <template is="dom-if" if=[[someCondition]]> with conditional rendering.

${this.someCondition ? html`<conditionally-rendered-element>` : ''}

2. Replace any <template is="dom-repeat" items=[[myItems]]> with map():

  ${this.myItems.map((item, index) => html`<some-item data="${item}"></some-item>`)

3. Look for on-foo-changed event listeners that were added by the script to replace Polymer double bindings. Ex:

<cr-input .value="${this.value_}" @value-changed="${this.onValueChanged_}">

Add a corresponding onFooChanged() method to the .ts file that updates the bound property from event.detail.value:

protected onFooChanged(e: CustomEvent<{value: string}>) {
  this.value_ = e.detail.value;
}

4. Update attribute bindings. Polymer uses "attr-name$=" syntax for attribute bindings. Replace this with "?attr-name=" if the attribute is a boolean, or "attr-name=" if the attribute is a string/number.

5. Update property bindings. Any other bindings that were bound using "property-name=" syntax should migrate to Lit's property syntax: ".propertyName=".

6. Look for properties that are passed to methods in the HTML. If the method is used in multiple places in the template with different parameters or is not a class method, keep the properties as parameters and add this. to reference them. Ex:

Replace:

<div aria-label="${this.i18n('foo', someProp)}"></div>
<button>${this.i18n('buttonLabel', somOtherProp)}</button>

with:

<div aria-label="${this.i18n('foo', this.someProp)}"></div>
<button>${this.i18n('buttonLabel', this.somOtherProp)}</button>

If a method is a class member method used in a single location, remove the property parameters in the template and change the method to reference them directly. Ex: if getDivClass() is only used in this location, then:

Replace:

<div class="${this.getDivClass(someProp, someOtherProp)}">

protected getDivClass(value: string, otherValue: string) {
  return value + ' ' + otherValue;
}

with

<div class="${this.getDivClass()}">

protected getDivClass() {
  return this.someProp + ' ' + this.someOtherProp;
}

7. Identify any enums that are reactive properties for the purposes of using them from the template, and replace by importing the enum directly in the .html.ts file. Then clean up the enum reactive property in the .ts file.