Global APIs (#111)

* feat: added composition API reference

* fix: changed define component link

* Update src/api/composition-api.md

Co-authored-by: Rahul Kadyan <[email protected]>

* Update src/api/composition-api.md

Co-authored-by: Rahul Kadyan <[email protected]>

* feat: added composition API reference

* fix: changed define component link

* fix: move arguments above usecases

* feat: added example for attrs destructuring

* fix: fixed `this` usage explanation

* feat: added explanation about inline event handler

* fix: added example to `isReactive`

* fix: grammar

* fix: grammar

* fix: removed raw values mention

* Addressed reviewers comments

* feat: moved reactivity APIs

* feat: moved reactivity utilities

* feat: separated advanced reactivity apis

* fix: fixed indentation

* fix: refactored reactivity API structure

* feat: added links to composition API

* fix: renamed proxy APIs to basic

* fix: fixed reactive typing

* fix: addressed reviewers comments

* fix: added async onInvalidate

* feat: added example for generic with unknown type

* feat: created table of contents

* feat: added createApp description

* feat: added h

* feat: added defineComponent

* chore: fixed todos

* Update src/api/global-api.md

Co-authored-by: Carlos Rodrigues <[email protected]>

* Update src/api/global-api.md

Co-authored-by: Carlos Rodrigues <[email protected]>

* Update src/api/global-api.md

Co-authored-by: Carlos Rodrigues <[email protected]>

* fix: reordered examples

Co-authored-by: Rahul Kadyan <[email protected]>
Co-authored-by: Carlos Rodrigues <[email protected]>

Author: 3 people

src/.vuepress/config.js

@@ -14,7 +14,7 @@ const sidebar = {
         '/guide/list',
         '/guide/events',
         '/guide/forms',
-        '/guide/component-basics',
+        '/guide/component-basics'
       ]
     },
     {
@@ -53,7 +53,12 @@ const sidebar = {
     {
       title: 'Scaling Up',
       collapsable: false,
-      children: ['/guide/routing', '/guide/state-management', '/guide/ssr', '/guide/accessibility']
+      children: [
+        '/guide/routing',
+        '/guide/state-management',
+        '/guide/ssr',
+        '/guide/accessibility'
+      ]
     },
     {
       title: 'Migration to Vue 3',
@@ -69,6 +74,7 @@ const sidebar = {
   api: [
     '/api/application-config',
     '/api/application-api',
+    '/api/global-api',
     {
       title: 'Options',
       collapsable: false,

src/api/application-api.md

@@ -271,4 +271,4 @@ setTimeout(() => app.unmount('#my-app'), 5000)
 
   When this method is called on the same plugin multiple times, the plugin will be installed only once.
 
-- **See also:** [Plugins](TODO)
+- **See also:** [Plugins](../guide/plugins.html)

src/api/composition-api.md

@@ -170,7 +170,7 @@ function setup(props: Data, context: SetupContext): Data
 ```
 
 ::: tip
-To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](TODO) is needed.
+To get type inference for the arguments passed to `setup()`, the use of [defineComponent](global-api.html#definecomponent) is needed.
 :::
 
 ## Lifecycle Hooks

src/api/computed-watch-api.md

@@ -218,7 +218,7 @@ type StopHandle = () => void
 
 ## `watch`
 
-The `watch` API is the exact equivalent of the Options API [this.\$watch](./instance-methods.html#watch) (and the corresponding [watch](./options-data.html#watch) option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
+The `watch` API is the exact equivalent of the Options API [this.$watch](./instance-methods.html#watch) (and the corresponding [watch](./options-data.html#watch) option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
 
 - Compared to [watchEffect](#watcheffect), `watch` allows us to:
 

src/api/global-api.md

@@ -0,0 +1,217 @@
+# Global API
+
+## createApp
+
+Returns an application instance which provides an application context. The entire component tree mounted by the application instance share the same context.
+
+```js
+const app = Vue.createApp({})
+```
+
+You can chain other methods after `createApp`, they can be found in [Application API](./application-api.html)
+
+### Arguments
+
+The function receives a root component options object as a first parameter:
+
+```js
+const app = Vue.createApp({
+  data() {
+    return {
+      ...
+    }
+  },
+  methods: {...},
+  computed: {...}
+  ...
+})
+```
+
+With the second parameter, we can pass root props to the application:
+
+```js
+const app = Vue.createApp(
+  {
+    props: ['username']
+  },
+  { username: 'Evan' }
+)
+```
+
+
+```html
+<div id="app">
+  <!-- Will display 'Evan' -->
+  {{ username }}
+</div>
+```
+
+### Typing
+
+```ts
+interface Data {
+  [key: string]: unknown
+}
+
+export type CreateAppFunction<HostElement> = (
+  rootComponent: PublicAPIComponent,
+  rootProps?: Data | null
+) => App<HostElement>
+```
+
+## h
+
+Returns a returns "virtual node", usually abbreviated to **VNode**: a plain object which contains information describing to Vue what kind of node it should render on the page, including descriptions of any child nodes. It is intended for manually written [render functions](../guide/render-function.md):
+
+```js
+render() {
+  return Vue.h('h1', {}, 'Some title')
+}
+```
+
+### Arguments
+
+Accepts three arguments: `tag`, `props` and `children`
+
+#### tag
+
+- **Type:** `String | Object | Function | null`
+
+- **Details:**
+
+  An HTML tag name, a component, an async component or null. Using null would render a comment. This parameter is required
+
+#### props
+
+- **Type:** `Object`
+
+- **Details:**
+
+  An object corresponding to the attributes, props and events we would use in a template. Optional
+
+#### children
+
+- **Type:** `String | Array | Object`
+
+- **Details:**
+
+  Children VNodes, built using `h()`, or using strings to get "text VNodes" or an object with slots. Optional
+
+  ```js
+  h('div', {}, [
+    'Some text comes first.',
+    h('h1', 'A headline'),
+    h(MyComponent, {
+      someProp: 'foobar'
+    })
+  ])
+  ```
+
+## defineComponent
+
+Implementation-wise `defineComponent` does nothing but return the object passed to it. However, in terms of typing, the returned value has a synthetic type of a constructor for manual render function, TSX and IDE tooling support.
+
+### Arguments
+
+An object with component options
+
+```js
+import { defineComponent } from 'vue'
+
+const MyComponent = defineComponent({
+  data() {
+    return { count: 1 }
+  },
+  methods: {
+    increment() {
+      this.count++
+    }
+  }
+})
+```
+
+## defineAsyncComponent
+
+Creates an async component that will be loaded only when it's necessary.
+
+### Arguments
+
+For basic usage, `defineAsyncComponent` can accept a a factory function returning a `Promise`. Promise's `resolve` callback should be called when you have retrieved your component definition from the server. You can also call `reject(reason)` to indicate the load has failed.
+
+```js
+import { defineAsyncComponent } from 'vue'
+
+const AsyncComp = defineAsyncComponent(() =>
+  import('./components/AsyncComponent.vue')
+)
+
+app.component('async-component', AsyncComp)
+```
+
+When using [local registration](../guide/component-registration.html#local-registration), you can also directly provide a function that returns a `Promise`:
+
+```js
+import { createApp, defineAsyncComponent } from 'vue'
+
+createApp({
+  // ...
+  components: {
+    components: {
+      AsyncComponent: defineAsyncComponent(() =>
+        import('./components/AsyncComponent.vue')
+      )
+    }
+  }
+})
+```
+
+For advanced usage, `defineAsyncComponent` can accept an object:
+
+The `defineAsyncComponent` method can also return an object of the following format:
+
+```js
+import { defineAsyncComponent } from 'vue'
+
+const AsyncComp = defineAsyncComponent({
+  // The factory function
+  loader: () => import('./Foo.vue')
+  // A component to use while the async component is loading
+  loadingComponent: LoadingComponent,
+  // A component to use if the load fails
+  errorComponent: ErrorComponent,
+  // Delay before showing the loading component. Default: 200ms.
+  delay: 200,
+  // The error component will be displayed if a timeout is
+  // provided and exceeded. Default: Infinity.
+  timeout: 3000,
+  // A function that returns a boolean indicating whether the async component should retry when the loader promise rejects
+  retryWhen: error => error.code !== 404,
+  // Maximum allowed retries number
+  maxRetries: 3,
+  // Defining if component is suspensible
+  suspensible: false
+})
+```
+
+**See also**: [Dynamic and Async components](../guide/component-dynamic-async.html)
+
+## nextTick
+
+Defer the callback to be executed after the next DOM update cycle. Use it immediately after you’ve changed some data to wait for the DOM update.
+
+```js
+import { createApp, nextTick } from 'vue'
+
+const app = createApp({
+  setup() {
+    const message = ref('Hello!')
+    const changeMessage = async newMessage => {
+      message.value = newMessage
+      await nextTick()
+      console.log('Now DOM is updated')
+    }
+  }
+})
+```
+
+**See also**: [`$nextTick` instance method](instance-methods.html#nexttick)

src/api/instance-methods.md

@@ -251,7 +251,7 @@
 
 - **Usage:**
 
-  Defer the callback to be executed after the next DOM update cycle. Use it immediately after you've changed some data to wait for the DOM update. This is the same as the global `Vue.nextTick`, except that the callback's `this` context is automatically bound to the instance calling this method.
+  Defer the callback to be executed after the next DOM update cycle. Use it immediately after you've changed some data to wait for the DOM update. This is the same as the global `nextTick`, except that the callback's `this` context is automatically bound to the instance calling this method.
 
 - **Example:**
 
@@ -274,4 +274,4 @@
   })
   ```
 
-- **See also:** [Vue.nextTick](TODO)
+- **See also:** [nextTick](global-api.html#nexttick)

src/api/options-composition.md

@@ -221,7 +221,7 @@ The `setup` function is a new component option. It serves as the entry point for
   </script>
   ```
 
-  Note that [refs](TODO) returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
+  Note that [refs](refs-api.html#ref) returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
 
 - **Usage with Render Functions / JSX**
 
@@ -318,4 +318,4 @@ The `setup` function is a new component option. It serves as the entry point for
 
   - Having `props` as a separate argument makes it easier to type it individually without messing up the types of other properties on the context. It also makes it possible to keep a consistent signature across `setup`, `render` and plain functional components with TSX support.
 
-- **See also:** [Composition API](TODO)
+- **See also:** [Composition API](composition-api.html)

src/api/options-dom.md

@@ -62,4 +62,4 @@
   The `render` function has priority over the render function compiled from `template` option or in-DOM HTML template of the mounting element
   :::
 
-- **See also:** [Render Functions](TODO)
+- **See also:** [Render Functions](../guide/render-function.html)

src/guide/component-basics.md

@@ -75,7 +75,7 @@ For example, you might have components for a header, sidebar, and content area,
 To use these components in templates, they must be registered so that Vue knows about them. There are two types of component registration: **global** and **local**. So far, we've only registered components globally, using `component` method of created app:
 
 ```js
-const app = Vue.createApp()
+const app = Vue.createApp({})
 
 app.component('my-component-name', {
   // ... options ...

src/guide/component-dynamic-async.md

@@ -76,7 +76,7 @@ const AsyncComp = defineAsyncComponent(() =>
 app.component('async-component', AsyncComp)
 ```
 
-You can also use `defineAsyncComponent` when [registering a component locally](components-registration.html#Local-Registration):
+You can also use `defineAsyncComponent` when [registering a component locally](component-registration.html#local-registration):
 
 ```js
 import { createApp, defineAsyncComponent } from 'vue'
@@ -97,4 +97,4 @@ Async components are _suspensible_ by default. This means if it has a [`<Suspens
 
 The async component can opt-out of `Suspense` control and let the component always control its own loading state by specifying `suspensible: false` in its options.
 
-You can check the list of available options in the [API Reference](TODO)
+You can check the list of available options in the [API Reference](../api/global-api.html#arguments-4)