feat(api): add top-level "addedIn" key support (quasarframework#7105)

* feat(api): include top-level "addedIn"

* chore(api): add top-level "addedIn" key

* chore: add vscode debug helper (F5 to start debugging build)

* Delete launch.json

Co-authored-by: Razvan Stoenescu <razvan.stoenescu@gmail.com>

Author: hawkeye64

ui/build/build.api.js

@@ -36,9 +36,9 @@ function getMixedInAPI (api, mainFile) {
 }
 
 const topSections = {
-  plugin: [ 'meta', 'injection', 'quasarConfOptions', 'props', 'methods' ],
-  component: [ 'meta', 'behavior', 'quasarConfOptions', 'props', 'slots', 'scopedSlots', 'events', 'methods' ],
-  directive: [ 'meta', 'quasarConfOptions', 'value', 'arg', 'modifiers' ]
+  plugin: [ 'meta', 'injection', 'quasarConfOptions', 'addedIn', 'props', 'methods' ],
+  component: [ 'meta', 'behavior', 'quasarConfOptions', 'addedIn', 'props', 'slots', 'scopedSlots', 'events', 'methods' ],
+  directive: [ 'meta', 'quasarConfOptions', 'addedIn', 'value', 'arg', 'modifiers' ]
 }
 
 const objectTypes = {
@@ -309,6 +309,36 @@ function parseObject ({ banner, api, itemName, masterType, verifyCategory }) {
   })
 }
 
+// https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+// https://regex101.com/r/vkijKf/1/
+const SEMANTIC_REGEX = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
+
+function isValidVersion (version) {
+  return !!SEMANTIC_REGEX.exec(version)
+}
+
+function handleAddedIn (api, banner) {
+  if (api['addedIn'] === void 0 || api['addedIn'].length === 0) {
+    logError(`${banner} "addedIn" is empty`)
+    console.log()
+    process.exit(1)
+  }
+
+  const addedIn = api['addedIn']
+
+  if (addedIn.charAt(0) !== 'v') {
+    logError(`${banner} "addedIn" value (${addedIn}) must start with "v"`)
+    console.log()
+    process.exit(1)
+  }
+
+  if (isValidVersion(addedIn.slice(1)) !== true) {
+    logError(`${banner} "addedIn" value (${addedIn}) must follow sematic versioning`)
+    console.log()
+    process.exit(1)
+  }
+}
+
 function convertBehavior (api, banner) {
   const behavior = {}
 
@@ -364,6 +394,11 @@ function parseAPI (file, apiType) {
       continue
     }
 
+    if (type === 'addedIn') {
+      handleAddedIn(api, banner)
+      continue
+    }
+
     if (['value', 'arg', 'quasarConfOptions', 'meta'].includes(type)) {
       if (Object(api[type]) !== api[type]) {
         logError(`${banner} "${type}"/"${type}" is not an object`)

ui/src/components/file/QFile.json

@@ -5,6 +5,8 @@
     "docsUrl": "https://v1.quasar.dev/vue-components/file"
   },
 
+  "addedIn": "v1.8.0",
+
   "props": {
     "value": {
       "type": [ "File", "FileList", "Array" ],

ui/src/components/intersection/QIntersection.json

@@ -9,6 +9,8 @@
     "$listeners": true
   },
 
+  "addedIn": "v1.4.0",
+
   "props": {
     "tag": {
       "examples": [ "div", "span", "blockquote" ],

ui/src/components/responsive/QResponsive.json

@@ -9,6 +9,8 @@
     "$listeners": true
   },
 
+  "addedIn": "v1.9.0",
+
   "slots": {
     "default": {
       "extends": "default"

ui/src/components/skeleton/QSkeleton.json

@@ -9,6 +9,8 @@
     "$listeners": true
   },
 
+  "addedIn": "v1.6.0",
+
   "props": {
     "dark": {
       "extends": "dark"

ui/src/components/virtual-scroll/QVirtualScroll.json

@@ -5,6 +5,8 @@
     "docsUrl": "https://v1.quasar.dev/vue-components/virtual-scroll"
   },
 
+  "addedIn": "v1.1.0",
+
   "props": {
     "type": {
       "type": "String",

ui/src/directives/Intersection.json

@@ -3,6 +3,8 @@
     "docsUrl": "https://v1.quasar.dev/vue-directives/intersection"
   },
 
+  "addedIn": "v1.3.0",
+
   "value": {
     "type": [ "Object", "Function" ],
     "desc": "Function to call when scrolling occurs (identical to description of 'handler' prop of the Object form); If using the Object form, it is HIGHLY recommended to reference it from your vue component scope, otherwise the directive update cycle will continuously recreate the observer which hits performance hard",

ui/src/directives/Mutation.json

@@ -3,6 +3,8 @@
     "docsUrl": "https://v1.quasar.dev/vue-directives/mutation"
   },
 
+  "addedIn": "v1.3.0",
+
   "value": {
     "type": [ "Function" ],
     "desc": "Function to call when mutation occurs; It is HIGHLY recommended to reference it from your vue component scope, otherwise the directive update cycle will continuously recreate the observer which hits performance hard",

ui/src/plugins/Dark.json

@@ -5,6 +5,8 @@
 
   "injection": "$q.dark",
 
+  "addedIn": "v1.3.0",
+
   "props": {
     "isActive": {
       "type": "Boolean",