Reading/Web/Desktop Improvements/Vue.js case study/Status log

2020-06-01 (draft)

 * What should we call the library?
 * Pushed out another week by request. Submissions due Tuesday.

2020-05-26
In contrast to the week prior, last week was mostly communications and planning. Some super important and needed conversations are happening. Here are some of the bigger ones.


 * Gerrit v GitHub
 * This will matter less for internal developers if we have a build step. If we don’t have a build step, GitHub may be needed to support our workflows.
 * What should we call the library?
 * No banana-themed names mentioned so far. Is this thing on? Where are my bananologists at?
 * [Spike] Should shared components be compiled for Vue.js search?
 * Positive feedback so far from Web and Roan
 * [Spike] Build step, ResourceLoader, or both for Vue.js search?
 * Holger is digging in.
 * Prototype presentations and shareouts in super-happy-dev-time and Web, #front-end and #readers-web-team Slack channels.
 * Phabricator tickets revised as needed.
 * What does internationalization look like for typeahead search?
 * This is being discussed for the scope of the search project with Santosh on ticket.
 * If you signed up for the training, you should have received notice to save the dates. Paperwork is in the signing process ℅ Adam.
 * Less grid discussion is ongoing.

Up next

 * Patches for NPM, NVM, and readme will be merging soon.
 * [Spike] Build step, ResourceLoader, or both for Vue.js search?
 * [Spike] Should shared components be compiled for Vue.js search?
 * What should be the components baseline? ContentTranslation lib?
 * What should the styling strategy be? wikimedia.ui, mediawiki.ui, something else?

2020-05-18

 * We’ll be closing out the WMDE and labs prototype tasks soon and revising the task tree this week as needed. The prototype is up (of note, see min+gz splits for different chunks). It’s mostly a copy of Santhosh’s base components with an amalgamation of past Web experiences and a lot of experimentation in library form.
 * Santhosh’s base library + grid (called “primitives”) with mediawiki.ui.button compatibility (likely compatible with other mediawiki.ui modules but they haven’t been extracted yet). The chunks are mix and match as needed.
 * Development workflow is promising and it’s nice to work with components in isolation.
 * An Action API client is provided initially. It can be swapped out later.
 * All scripts are TypeScript but compiled to ES5, all styles are Less but compile to CSS.
 * The library is very component-centric. All pieces relevant to a given component are colocated except when shared. The bundler splits the pieces as needed according to the entries and common chunks wanted.
 * Most useful reports are automated as part of the docs NPM script.


 * We set up a provisional repo to collaborate better on experimentation and start scaffolding. Please watch this repo if you wish to participate.
 * Vector testbed integration will be coming. We need to work out how to consume a library in Vector.


 * Even more build step discussions coming. Please participate.

2020-05-11
I’ve aggregated some notes here from Holger, Web, and prototyping as it relates to the search Vue.js project. Share this document with whomever you wish. Comments are welcome but the document itself is a one-off and will not be maintained by Holger or myself. There’s a lot in flight.

Scaffolding

 * A number of projects are using the Vue CLI, notably WMDE and ContentTranslation. This is the Vue equivalent of Create React App which is billed as "Set up a modern web app by running one command." In other words, a zero-config tool. Zero-configs are excellent for prototypes but terrible for scaling. That is, they’re leaky abstractions that are wonderfully free of implementation complexity until the moment they need a non-zero configuration. For example, ejecting the underlying Webpack configuration for the Vue CLI is ~1600 lines for the WMDE’s components and ~1500 lines for ContentTranslation. How do you manage that complexity once you’ve already scaled the functional part of the project? Most of those configurations are unused boilerplate for a diversity of use cases. It is simpler to invest in the underlying tool from the beginning.  For Vue.js search, I recommend we avoid Vue CLI and use the constituent pieces wanted directly. This is the approach I’m taking in my current prototype.  More related Slack discourse on zero-config tools here.
 * Holger has concluded that Vue.js v2 is the best choice for the scope of the search project. Check out his v2 vs v3 mindmap! I’m going to sign this task off soon if no one raises objections. That means add a Vue.js v2 runtime-only Core ResourceLoader module will be ready to work on.
 * Jon and Nick worked with Roan to provide some nice task definitions for swapping out the JavaScript search implementations so we only have to ship one implementation’s payload. This improves our limited byte budget $$$
 * Alex has completed some very nice mocks for the new search header (that’s the location, not the form) and revised the implementation task.
 * Core Platform Team’s new REST API (not RESTBase) is mostly up on the beta cluster. |description&uselang=content&smaxage=300&maxage=300&generator=prefixsearch&pilicense=any&piprop=thumbnail&pithumbsize=160&gpssearch=red&origin=* Compare to the Action API:
 * Only one query parameter needed. Less flexible but designed for search.
 * Semantic API version is in the path.
 * JSON format is assumed.
 * Results are already ordered by relevance (no index property).
 * No pagination. Up to 50 results.
 * Documentation isn’t quite complete. I saw some useful typing information here.
 * The “search pages containing” API looks similar. Just change the title path to page. I’ve got an Action client locally in my prototype that we can swap out if we hit any blockers but the REST API looks like it’s nearly ready for prod. I’m thinking the search component will allow for the client to be passed in but default to the REST API if none is specified. Our work will be covered in “build the Vue.js search component network client.”
 * The WMDE Vue.js component library has been a great reference. Some notes and highlights so far:
 * All Vue v2.
 * All scripts and modules are TypeScript. In my prototype, I’m using the TypeScript compiler for transpiling both TypeScript and general non-ES5 JavaScript. The Popups ES5 linter (now powered by eslint-config-wikimedia) has been an invaluable reference that caught some flaws in my initial config and is now included in the prototype. As I understand it, Core briefly offered ES6 because this linter was missing.
 * Components are class based. In my own experiments, this adds a few kibibytes minified to the overall bundle so I’m currently using `Vue.component` instead to see how that goes.
 * The library depends on a small part of lodash for debouncing. I’d like to avoid that if possible. I think we will need some implementation for throttling the network queries but I don’t know what that will be yet.
 * I couldn't get the source maps to line up correctly in the time I had but it's clocking in at about 13Ki minified JavaScript for four simple components (~600 lines) using the terser minifier on the final build product and 3Ki minified CSS.
 * SCSS is used for styling. I’ll talk about why LESS seems more appealing in the ContentTranslation bullet.
 * Comes with a Docker config. I’m hoping we can defer and use NVM and/or Timo's Fresh if it is essential. Maybe this can be mostly docs.
 * Dumps components out at the entry point which seems nice to me for a shared library.
 * In general, a lot of scaffolding to inform. Holger will be digging into the WMDE prototype task to help identify lessons learned and what we should build upon.
 * More related notes.
 * The ContentTranslation repo is very impressive. Some notes:
 * Wow, what a button! I’ve copied this and part of the icon into my current prototype.
 * There's a lot of LESS needed to make a dazzling button. In my understanding, the approach Santosh used is to make the buttons mediawiki.ui ResourceLoader module compatible (read: almost a file copy). Meaning, I think we may be able to swap the existing LESS RL module instead of shipping the mediawiki.ui module effectively twice. There are also component specific styles so I’m not sure how this works yet but I think we could concatenate uncompiled LESS for the components only (no mediawiki.ui). If possible, I like this approach because we desperately want to minimize bytes shipped for the pilot project which has high interactivity needs and I can't shrink the Vue framework more than the runtime which is ~63 Ki minified by itself(!). As I understand it, the downside is that we can't practically use the wikimedia-ui-base repo which I had been planning to use. I’ll be continuing to explore this.
 * The ContentTranslation JavaScript needed for just the mediawiki.ui is a modest 8.9 Ki minified but the vendor dependencies are 180 Ki (of which I expect a third is Vue itself--I didn't see any source maps). In one of my own Vue CLI-based prototypes, I see a large footprint by Core JS and polyfills but I’d need to look deeper.
 * Jan’s Portals search implementation is one of our best and uses plain JavaScript. It has a lot of legacy browser support that is no longer necessary and, of course, isn’t Vue-based. My previous prototype was largely based on this work. The next will mostly be a mix of Portals and ContentTranslation designed for integration with the dependencies already present in the main namespace.
 * Storybook is about to make a breaking migration (currently beta) that has extensive changes. I’ve started with the beta since it’s all docs anyway, not needed to ship, and I want to avoid acquiring experience in soon-to-be irrelevant tech. There are some nice stories in ContentTranslation already.
 * In general, lots of exploration into how the assets will be divided. Current thinking in the prototype:
 * mediawiki.ui is provided by the library but the Core ResourceLoader module is used in production.
 * Components are completely bundled together as a single entry for search. In the future, different entries may provide different splits.
 * No dependencies except Vue itself at the moment which will be provided by Core.
 * The components are going to be in a separate repo per Nick’s good work and Holger’s sign off. Because the components are in a separate repo, we need to include them in Vector somehow. That means an NPM package, a Git submodule, file copying, or something else. An NPM package seems the most sensible to me as it’s the standard but it implies Webpack in Vector. This question will be answered in build step, ResourceLoader, or both for Vue.js search?
 * Build step discussion is ongoing. Participation is welcome but the effort is championed by Joe Walsh.

Coming soon

 * Sign off of Vue 2 / 3 task.
 * Vue.js training request. Last call to sign up here.
 * Hosted prototype targeting some time next week to help guide some of the work. It will be an amalgamation of the Portals implementation, ContentTranslation, and many other references.
 * Task prioritization today.

Button references
There are many ways to build a button it seems!

Within Wikimedia
https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/ContentTranslation/+/master/app/src/lib/mediawiki.ui/components/MWButton.vue (Santhosh’s button)

https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/Wikibase/+/master/client/data-bridge/src/presentation/components/EventEmittingButton.vue (WMDE’s button?)

https://github.com/egardner/mediawiki-extensions-MachineVision/blob/vue-js/resources/components/base/Button.vue (Anne / Roan’s button?)

https://github.com/wikimedia/mediawiki-extensions-NearbyPages/blob/master/resources/ext.nearby.scripts/Button.vue (NearbyPages)

Outside Wikimedia
https://github.com/ElemeFE/element/blob/dev/packages/button/src/button.vue

https://github.com/myliang/fish-ui/blob/master/src/components/Button.vue

https://github.com/buefy/buefy/blob/dev/src/components/button/Button.vue

https://github.com/museui/muse-ui/blob/master/src/Button/Button.js

https://github.com/vuetifyjs/vuetify/blob/master/packages/vuetify/src/components/VBtn/VBtn.ts

https://github.com/vuematerial/vue-material/blob/dev/src/components/MdButton/MdButton.vue

https://github.com/view-design/ViewUI/blob/master/src/components/button/button.vue

https://github.com/JosephusPaye/Keen-UI/blob/next/src/UiButton.vue

Within Wikimedia
We love reimplementing search!

https://www.mediawiki.org/wiki/User:JDrewniak_(WMF)/notes/Search_widgets_at_Wikimedia (Jan’s notes--there are so many implementations at Wikimedia!)


 * https://gerrit.wikimedia.org/r/plugins/gitiles/wikimedia/portals/+/master/dev/wikipedia.org/assets/js/ (Jan’s portal implementation)
 * https://github.com/wikimedia/mediawiki/blob/master/resources/src/mediawiki.searchSuggest/searchSuggest.js
 * https://github.com/wikimedia/mediawiki/blob/master/resources/src/mediawiki.widgets/mw.widgets.TitleWidget.js

https://phabricator.wikimedia.org/T244392#6041060 (Timo’s notes)

I think Roan did one in Vue I need to find.

Outside Wikimedia
https://github.com/MadimetjaShika/vuetify-google-autocomplete/blob/dev/src/vga/VuetifyGoogleAutocomplete.js

https://vuetifyjs.com/en/components/autocompletes/

https://haltersweb.github.io/Accessibility/autocomplete.html