[Polymer 3.0-preview] Preliminary research on Polymer 3.0 support (ES Modules instead of HTML Imports)

[t2ym]

[Polymer 3.0-preview] Preliminary research on Polymer 3.0 support (ES Modules instead of HTML Imports)

Proof of Concept Demo Page on GitHub Pages with Polymer 3.0-preview and many inelegant patches and temporary hacking

link to GitHub pages

Notes

• The PoC page sources are available at gh-pages branch
• The components (i18n-element, i18n-behavior, i18n-format, i18n-number) are converted by polymer-modulizer
• Many patching and hacking on the converted sources, which are not working as they are converted
• Npm modules have not been published yet.
• Native ES modules without module bundling

Main hacking

• this._i18nPreprocess() to static get template() (automated below)

  class I18nSubclassElement extends BaseElements.I18nElement {
  static get importPath() {
  return import.meta.url;
  }
  
  static get template() {
  return this._i18nPreprocess(html`
  <span id="label1">Subclass UI label 1</span><br>
  <span id="label2">Subclass UI label 2</span><br>
  <span id="label3">Subclass UI label 3</span><br>
  <span>complex <b>parameterized</b> sentences <i>abc</i></span><br>
  <input placeholder="localizable attribute" i18n-attr="i18n attr">
  `);
  }
  ...
  }

• The above hacking is automated in this change

  class I18nSubclassElement extends BaseElements.I18nElement {
  static get importPath() {
  return import.meta.url;
  }
  
  static get template() {
  return html`
  <span id="label1">Subclass UI label 1</span><br>
  <span id="label2">Subclass UI label 2</span><br>
  <span id="label3">Subclass UI label 3</span><br>
  <span>complex <b>parameterized</b> sentences <i>abc</i></span><br>
  <input placeholder="localizable attribute" i18n-attr="i18n attr">
  `;
  }
  ...
  }

  return class Localizable extends mixinBehaviors([BehaviorsStore._I18nBehavior], base) {
  constructor () {
    Localizable._renameTemplate(new.target);
    Localizable.template;
    super();
  }
  static _renameTemplate(target) {
    let desc = Object.getOwnPropertyDescriptor(target, 'template');
    if (desc) {
      Object.defineProperty(target, '_rawTemplate', desc);
      Reflect.deleteProperty(target, 'template');
    }
  }
  static get template() {
    return this._i18nPreprocess(this._rawTemplate);
  }
  ...

Main Issues and Tasks (There are many other issues)

• Some dependent modules like deepcopy@0.6.3, make-plural@3 are incompatible with ES modules.
  • Their UMD wrappers are hacked
  • root from this which is undefined in modules is temporarily replaced with window
  • Newer versions with ES module compatibility should be used
• document.currentScript is null in modules
  • document.currentScript is used for getting ownerDocument, which is the starting point of searching templates in HTML Imports, which are not used in Polymer 3.0
  • Ad-hoc hack: ownerDocument defaults to document
• resolveUrl cannot handle relative paths without a valid importPath property
  • Base URLs of components should be extracted from import.meta.url
  • Chrome and Safari support import.meta.url. Status for Firefox and Edge is unknown.
  • polymer-modulizer has --add-import-path option to add a static property importPath, which returns import.meta.url, to each element class
• [x] static get template() has to be wrapped by this._i18nPreprocess()
  • [x] Can be automated as above
• Integration with gulp-i18n-preprocess
  • The same approach as #57 should be valid
  • A PoC demo/gulpfile.js is added
• Declarative <i18n-attr-repo> attribute declarations are ineffective to <i18n-dom-bind> elements in Chrome and all elements in Safari
  • <i18n-dom-bind> references the repository of <i18n-attr-repo> too early.
  • Can binding and rendering in <i18n-dom-bind> be delayed until declarative <i18n-attr-repo> elements become effective?
  • Imperative <i18n-attr-repo> handling is awkward
• Handle tests
  • link to test on GitHub pages
• Side-effects of bundling by the coming polymer-bundler 4.0 and webpack are unknown
  • importPath may have an inappropriate value for retrieving JSON resources for locales
  • Issue on polymer-bundler: Figure out how to handle import.meta.url
• There should be no manual patching when Polymer 3.0 and polymer-modulizer are released

[t2ym]

Temporary hacking in converted legacy components (automated below and in this change)

Polymer({
  importPath: import.meta.url,
  __template: html`
    <span id="label1">Legacy UI label 1</span><br>
    <span id="label2">Legacy UI label 2</span><br>
    <span id="label3">Legacy UI label 3</span>
`,

  get _template() {
    if (this instanceof HTMLElement && !this.constructor._templateLocalizable) {
      this.constructor._templateLocalizable = BehaviorsStore._I18nBehavior._constructDefaultBundle(this.__template, this.is);
    }
    return this.__template;
  },

  set _template(t) {
    //this.__template = t;
  },

  is: 'i18n-legacy-element',

  behaviors: [
    BehaviorsStore.I18nBehavior
  ]
});

Automated _template conversion via i18n-behavior/i18n-behavior.js

  if (ElementMixin) {
    // Polymer 2.x
    BehaviorsStore._I18nBehavior = BehaviorsStore.I18nBehavior;
    BehaviorsStore.I18nBehavior = [ BehaviorsStore._I18nBehavior ];
    if (!document.currentScript) {
      // Polymer 3.x
      BehaviorsStore.I18nBehavior.push({
        get _template() { 
          if (this.__template) {
            return this.__template;
          }
          if (this instanceof HTMLElement &&
            this.constructor.name === 'PolymerGenerated' &&
            !this.constructor.__finalizeClass) {
            this.constructor.__finalizeClass = this.constructor._finalizeClass;
            this.constructor._finalizeClass = function _finalizeClass() {
              let info = this.generatedFrom;
              if (!this._templateLocalizable) {
                if (info._template) {
                  this._templateLocalizable = BehaviorsStore._I18nBehavior._constructDefaultBundle(info._template, info.is);
                }
                else {
                  let template = DomModule.import(info.is, 'template');
                  if (template) {
                    this._templateLocalizable = BehaviorsStore._I18nBehavior._constructDefaultBundle(template, info.is);
                  }
                }
              }
              if (!this.hasOwnProperty('importPath')) {
                Object.defineProperty(this, 'importPath', { value: info.importPath });
              }
              return this.__finalizeClass();
            }
          }
          return null;
        },
        set _template(value) {
          this.__template = value;
        }
      });
    }

[t2ym]

Browser Status

Browsers	Version	PoC Working	Notes
Chrome	64+	✅
Firefox	Nightly 60.0a1	w/ patch below	import.meta.url is not implemented; Bugzilla 1427610 Implement import.meta
Safari	TP 49 (Safari 11.2, WebKit 13606.1.3.3)+	✅
Edge	17.17101+	w/ patch below	import.meta.url is not implemented

Patch import.meta.url (just for PoC)

• link to patched GitHub Pages

Service Worker to replace import.meta.url with a literal string of response.url value

addEventListener('fetch', function (event) {
  if (event.request.method === 'GET') {
    event.respondWith(async function() {
      let response = await fetch(event.request);
      if (response.status === 200 && response.type !== 'opaque') {
        let url = new URL(response.url);
        if (url.pathname.match(/[.]js$/)) {
          let code = await response.text();
          if (code.indexOf('import.meta.url') >= 0) {
            code = code.replace(/import[.]meta[.]url/g, '\'' + response.url + '\'');
          }
          response = new Response(code, { headers: {'Content-Type': 'text/javascript'} });
        }
      }
      return response;
    }());
  }
});

[t2ym]

Integration with gulp-i18n-preprocess

gulp tasks

cd i18n-element/components/i18n-element/demo
../node_modules/.bin/gulp

unmodulize gulp filter to generate temporary HTMLs from JS modules

• Assuming each file base name is the same as its component name.

  var unmodulize = gulpif('**/*.js', through.obj(function (file, enc, callback) {
  let htmlTemplate = `<!-- temporary HTML --><link rel="import" href="../../../i18n-element.html"><innerHTML><dom-module>`;
  let code = stripBom(String(file.contents));
  let template = code.match(/html`([^`]*)`/);
  let innerHTML = code.match(/[.]innerHTML = `([^`]*)`/);
  let name = file.path.split('/').pop().replace(/[.]js$/,'');
  if (template || innerHTML) {
  let html = htmlTemplate;
  if (template) {
    html = html.replace('<dom-module>', 
      `<dom-module id="${name}"><template>${template[1]}</template></dom-module>\n`);
  }
  else {
    html = html.replace('<dom-module>', '');
  }
  if (innerHTML) {
    html = html.replace('<innerHTML>', innerHTML[1]);
  }
  else {
    html = html.replace('<innerHTML>', '');
  }
  let htmlFile = new gutil.File({
    cwd: file.cwd,
    base: file.base,
    path: file.path.substring(0, file.path.length - 3) + '.html',
    contents: new Buffer(html)
  });
  console.log('unmodulize: htmlFile.path = ', htmlFile.path, ' name = ', name, 'html = ', html);
  this.push(htmlFile);
  }
  callback(null, file);
  }));

  i18n gulp task

  gulp.task('i18n', () => {
  return gulp.src([ 'poc/**/* ' ], { base: 'poc' })
  .pipe(unmodulize) // generate temporary HTMLs from ES modules
  .pipe(scan) // generate attributesRepository by scanning <i18n-attr-repo>
  .pipe(basenameSort) // sort by component names
  .pipe(dropDefaultJSON) // drop old default (English) JSONs
  .pipe(preprocess) // preprocess temporary HTMLs and generate new default JSONs
  .pipe(tmpHTML) // put preprocessed HTMLs to .tmp directory (not used)
  .pipe(dropDummyHTML) // drop the preprocessed HTMLs
  .pipe(tmpJSON) // put new default JSONs to .tmp directory
  .pipe(importXliff) // import XLIFF to JSONs
  .pipe(leverage) // merge diffs between old and new default JSONs into localized JSONs
  .pipe(exportXliff) // export XLIFF from JSONs
  .pipe(feedback) // feedback to existing JSONs
  .pipe(debug({ title: title }))
  .pipe(size({ title: title }))
  .pipe(gulp.dest('poc')); // output to the same directory
  });

[t2ym]

Close as #60 is closed.