adjusted vue implementation following vue 3 migration guide, refactored vue implementation on the way, removed vuex and v-runtime-template dependency, started Matestack 3 migration guide

Author: jonasjabari

Gemfile

@@ -14,7 +14,7 @@ gemspec
 group :development, :test do
   gem 'rspec-rails', '~> 4.0.2'
   gem 'capybara'
-  gem 'webpacker', '~> 4.0'
+  gem 'webpacker', '~> 5.0'
   gem 'pg', '>= 0.18', '< 2.0'
   gem 'selenium-webdriver'
   gem 'puma'

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    matestack-ui-core (2.1.0)
+    matestack-ui-core (2.1.1)
       rails (>= 5.2)
 
 GEM
@@ -80,7 +80,7 @@ GEM
       xpath (~> 3.2)
     childprocess (3.0.0)
     coderay (1.1.3)
-    concurrent-ruby (1.1.8)
+    concurrent-ruby (1.1.9)
     crack (0.4.5)
       rexml
     crass (1.0.6)
@@ -93,19 +93,21 @@ GEM
     globalid (0.4.2)
       activesupport (>= 4.2.0)
     hashdiff (1.0.1)
-    i18n (1.8.10)
+    i18n (1.8.11)
       concurrent-ruby (~> 1.0)
-    loofah (2.9.1)
+    loofah (2.13.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mail (2.7.1)
       mini_mime (>= 0.1.1)
     marcel (1.0.1)
     method_source (1.0.0)
     mini_mime (1.0.3)
-    minitest (5.14.4)
+    mini_portile2 (2.7.1)
+    minitest (5.15.0)
     nio4r (2.5.7)
-    nokogiri (1.11.4-x86_64-linux)
+    nokogiri (1.13.0)
+      mini_portile2 (~> 2.7.0)
       racc (~> 1.4)
     pg (1.2.3)
     pry (0.13.1)
@@ -119,9 +121,9 @@ GEM
     public_suffix (4.0.6)
     puma (5.3.1)
       nio4r (~> 2.0)
-    racc (1.5.2)
+    racc (1.6.0)
     rack (2.2.3)
-    rack-proxy (0.6.5)
+    rack-proxy (0.7.2)
       rack
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
@@ -143,15 +145,15 @@ GEM
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.3.0)
+    rails-html-sanitizer (1.4.2)
       loofah (~> 2.3)
     railties (6.1.3.2)
       actionpack (= 6.1.3.2)
       activesupport (= 6.1.3.2)
       method_source
       rake (>= 0.8.7)
       thor (~> 1.0)
-    rake (13.0.3)
+    rake (13.0.6)
     regexp_parser (2.1.1)
     rexml (3.2.5)
     rspec-core (3.10.1)
@@ -175,6 +177,7 @@ GEM
     selenium-webdriver (3.142.7)
       childprocess (>= 0.5, < 4.0)
       rubyzip (>= 1.2.2)
+    semantic_range (3.0.0)
     simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
@@ -188,23 +191,24 @@ GEM
       actionpack (>= 4.0)
       activesupport (>= 4.0)
       sprockets (>= 3.0.0)
-    thor (1.1.0)
+    thor (1.2.1)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
     webmock (3.13.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    webpacker (4.3.0)
-      activesupport (>= 4.2)
+    webpacker (5.4.3)
+      activesupport (>= 5.2)
       rack-proxy (>= 0.6.1)
-      railties (>= 4.2)
+      railties (>= 5.2)
+      semantic_range (>= 2.3.0)
     websocket-driver (0.7.3)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
     xpath (3.2.0)
       nokogiri (~> 1.8)
-    zeitwerk (2.4.2)
+    zeitwerk (2.5.3)
 
 PLATFORMS
   ruby
@@ -222,7 +226,7 @@ DEPENDENCIES
   selenium-webdriver
   simplecov
   webmock
-  webpacker (~> 4.0)
+  webpacker (~> 5.0)
 
 BUNDLED WITH
    2.1.4

V3_MIGRATION.md

@@ -0,0 +1,222 @@
+# Installation & setup changes
+
+## IE 11 support dropped
+
+- vue3 dropped IE 11 support
+- when using babel alongside webpacker, please adjust your package.json or .browserslistrc config in order to exclude IE 11 support:
+
+```json
+{
+  "name": "my app",
+  "...": { },
+  "browserslist": [
+    "defaults",
+    "not IE 11" // <-- important!
+  ]
+}
+```
+
+Otherwise you may encounter issues around `regeneratorRuntime`
+
+## Setup via webpacker
+
+`config/webpack/environment.js`
+```js
+const { environment } = require('@rails/webpacker')
+const webpack = require('webpack');
+
+const customWebpackConfig = {
+  resolve: {
+    alias: {
+      vue: 'vue/dist/vue.esm-bundler',
+    }
+  },
+  plugins: [
+    new webpack.DefinePlugin({
+      __VUE_OPTIONS_API__: true,
+      __VUE_PROD_DEVTOOLS__: false
+    })
+  ]
+}
+
+environment.config.merge(customWebpackConfig)
+
+module.exports = environment
+```
+
+and then just use `import { whatever } from 'vue'` instead of `import { whatever } from 'vue/dist/vue.esm'`
+
+**Optional: vue3 compat build usage**
+
+- if you're using any vue2 APIs (or one of the libraries you're using), you can use the vue3 compat build
+- this enables you to use both vue2 and vue3 APIs and migrate step by step
+- usage via webpack config when using webpacker 5.x and up:
+
+`config/webpack/environment.js`
+```js
+const { environment } = require('@rails/webpacker')
+const webpack = require('webpack')
+
+const customWebpackConfig = {
+  resolve: {
+    alias: {
+      vue: '@vue/compat/dist/vue.esm-bundler',
+    }
+  },
+  plugins: [
+    new webpack.DefinePlugin({
+      __VUE_OPTIONS_API__: true,
+      __VUE_PROD_DEVTOOLS__: false
+    })
+  ]
+}
+
+environment.config.merge(customWebpackConfig)
+
+module.exports = environment
+```
+
+# vue.js changes
+
+## app definition and mount
+
+`javascript/packs/application.js`
+```js
+import { createApp } from 'vue'
+import MatestackUiCore from 'matestack-ui-core'
+
+const appInstance = createApp({})
+
+document.addEventListener('DOMContentLoaded', () => {
+  MatestackUiCore.mount(appInstance, '#matestack-ui') // use this mount method
+})
+```
+
+## custom component registration
+
+`some/component/file.js`
+```js
+import MatestackUiCore from 'matestack-ui-core'
+
+const myComponent = {
+  mixins: [MatestackUiCore.componentMixin],
+  template: MatestackUiCore.componentHelpers.inlineTemplate,
+  data() {
+    return {
+      foo: "bar"
+    };
+  },
+  mounted(){
+    console.log("custom component mounted")
+  }
+};
+
+export default myComponent
+```
+
+`javascript/packs/application.js`
+```js
+import { createApp } from 'vue'
+import MatestackUiCore from 'matestack-ui-core'
+
+import myComponent from 'some/component/file.js' // import component definition from source
+
+const appInstance = createApp({})
+
+appInstance.component('my-component', myComponent) // register at appInstance
+
+document.addEventListener('DOMContentLoaded', () => {
+  MatestackUiCore.mount(appInstance, '#matestack-ui')
+})
+```
+
+## component template
+
+- For application components, apply `template: MatestackUiCore.componentHelpers.inlineTemplate`
+
+`some/component/file.js`
+```js
+import MatestackUiCore from 'matestack-ui-core'
+
+const myComponent = {
+  mixins: [MatestackUiCore.componentMixin],
+  template: MatestackUiCore.componentHelpers.inlineTemplate, // this one!
+  data() {
+    return {
+      foo: "bar"
+    };
+  },
+  mounted(){
+    console.log("custom component mounted")
+  }
+};
+
+export default myComponent
+```
+
+- Only for core components
+  - add import `import componentHelpers from 'some/relative/path/to/helpers'`
+  - and then apply `template: componentHelpers.inlineTemplate`
+
+## component scope prefix
+
+- use `vc.` or `vueComponent.` in order to prefix all properties references or method calls within your vue.js component `response`
+
+`some/component/file.js`
+```js
+import MatestackUiCore from 'matestack-ui-core'
+
+const myComponent = {
+  mixins: [MatestackUiCore.componentMixin],
+  template: MatestackUiCore.componentHelpers.inlineTemplate,
+  data() {
+    return {
+      foo: "bar"
+    };
+  },
+  mounted(){
+    console.log(this.foo) // --> bar
+    // or:
+    console.log(vc.foo) // --> bar
+  }
+};
+
+export default myComponent
+```
+
+```ruby
+class Components::MyComponent < Matestack::Ui::VueJsComponent
+  vue_name "my-component"
+
+  def response
+    div do
+      plain "{{foo}}" # --> undefined!
+      plain "{{vc.foo}}" # --> bar
+    end
+  end
+end
+```
+
+## component $refs
+
+- use `this.getRefs()` instead of `this.$refs`
+
+## component $el
+
+- use `this.getElement()` instead of `this.$el`
+
+## component beforeDestroy hook
+
+- `beforeDestroy` was renamed to `beforeUnmount` within vue3
+- Search&Replace if your're using this hook in any of your vue components
+
+## $set, Vue.set
+
+- `this.$set` and `Vue.set` are removed in vue3 as they are not longer required for proper reactivity binding
+- If you use these methods, use plain JavaScript mutations instead
+
+# ruby changes
+
+## matestack wrapper method
+
+- removed, app wrapping is done within the app class directly now

lib/matestack/ui/core.rb

@@ -44,6 +44,7 @@ module VueJs
 require "#{vue_js_base_path}/components/form/context"
 require "#{vue_js_base_path}/components/form/base"
 require "#{vue_js_base_path}/components/form/form"
+require "#{vue_js_base_path}/components/form/nested_form"
 require "#{vue_js_base_path}/components/form/input"
 require "#{vue_js_base_path}/components/form/textarea"
 require "#{vue_js_base_path}/components/form/checkbox"