feat: add watchers' docs

src/docs/events.en-US.md

@@ -1,19 +1,19 @@
 ## Events
-### 原生事件
-通过 `onXXX` 的方式监听原生事件。
+### Native Events
+By prefixing the native event name with word `on`.
 
-```jsx
+```tsx
 import { QuarkElement, customElement } from "quarkc"
 
 @customElement({ tag: "quark-input", style })
 class Input extends QuarkElement {
 
   onClick = () => {
-    console.log("按钮被点击“)
+    console.log("btn clicked")
   }
 
   onInput = () => {
-    console.log("input 事件“)
+    console.log("input event")
   }
 
   render() {
@@ -27,44 +27,86 @@ class Input extends QuarkElement {
 }
 ```
 
-### 自定义事件
-通过 `$emit` 发送事件。
+### Custom Events
+By using instance method `$emit`. The first parameter is name of the event and the second parameter is the data to be passed. The passed data can be accessed via `event.detail`.
+
 ```tsx
 import { QuarkElement, customElement } from "quarkc"
 
 @customElement({ tag: "quark-input", style })
 class Input extends QuarkElement {
 
   onInput = () => {
-    this.$emit("input", {
-      detail: {
-        value: 'xxx',
-      },
+    // ❗ If your custom element will only be used as an internal component in Quarkc,
+    // you should avoid to use event name like `custom-event`
+    const data = {}
+    this.$emit("customEvent", {
+      detail: data,
+      // ...other event properties like `bubbles` goes here...
     })
   }
 
   render() {
     return (
-      <div>
-        <input onInput={this.onInput}></input>
-      </div>
+      <input onInput={this.onInput}></input>
     )
   }
 }
 ```
 
-然后在你的自定义元素上绑定事件：
+Then bind event listeners on your custom element:
 
+#### Vue
+```html
+<template>
+  <quark-input @custom-event="handler" id="quark-input" />
+</template>
+<script>
+  export default {
+    methods: {
+      handler(e) {
+        console.log(e.detail.value);
+      },
+    },
+  };
+</script>
+```
+
+#### React
 ```tsx
-/**Vue中*/
-<quark-input @input="this.onInput" id="quark-input"/>
+function App() {
+  const handler = (e) => {
+    console.log(e.detail.value);
+  };
+  return <quark-input onCustomEvent={handler} id="quark-input" />;
+}
 ```
 
-或者
+#### Quarkc
+❗Unlike Vue, hyphens in custom event names are not supported under the ground (when using `$emit`).
 
+❗Unlike React, custom event names will not be decapitalized.
 ```tsx
-/**其它任何框架或者无框架中*/
-const myInputElement = document.getElementById("quark-input")
-myInputElement.addEventListener('input', (evt) => {})
+@customElement({ tag: "quark-input-parent", style })
+class QuarkInputParent extends QuarkElement {
+  handler = (e) => {
+    console.log(e.detail.value)
+  }
+
+  render() {
+    // onCustomEvent ❌ For this use-case, use `CustomEvent` as `$emit` name
+    return (
+      <quark-input id="quark-input" oncustomEvent={this.handler} />
+    )
+  }
+}
 ```
- 通过 `this.$emit` 触发自定义事件，`emit` 的第一个参数为事件名，第二个参数为传递的参数。可通过 `evt.detail` 获取到传递的数据。
+
+#### Pure JS
+
+```ts
+const myInputElement = document.getElementById("quark-input")
+myInputElement.addEventListener('customEvent', (e) => {
+  console.log(e.detail.value)
+})
+```

src/docs/events.zh-CN.md

@@ -1,19 +1,19 @@
 ## 事件处理
 ### 原生事件
-通过 `onXXX` 的方式监听原生事件。
+通过在原生事件名前添加 `on` 前缀来绑定原生事件。
 
-```jsx
+```tsx
 import { QuarkElement, customElement } from "quarkc"
 
 @customElement({ tag: "quark-input", style })
 class Input extends QuarkElement {
 
   onClick = () => {
-    console.log("按钮被点击“)
+    console.log("按钮被点击")
   }
 
   onInput = () => {
-    console.log("input 事件“)
+    console.log("input事件")
   }
 
   render() {
@@ -28,43 +28,85 @@ class Input extends QuarkElement {
 ```
 
 ### 自定义事件
-通过 `$emit` 发送事件。
+通过使用实例方法 `$emit`来发送自定义事件。第一个参数是事件的名称，第二个参数是传递的数据。传递的数据可以通过 `event.detail` 获取。
+
 ```tsx
 import { QuarkElement, customElement } from "quarkc"
 
 @customElement({ tag: "quark-input", style })
 class Input extends QuarkElement {
 
   onInput = () => {
-    this.$emit("input", {
-      detail: {
-        value: 'xxx',
-      },
+    // ❗ 如果你的自定义元素只会作为 Quarkc 内部组件使用，
+    // 你应该避免使用诸如 `custom-event` 的事件名称
+    const data = {}
+    this.$emit("customEvent", {
+      detail: data,
+      // ...其他事件属性，例如 `bubbles` 等等...
     })
   }
 
   render() {
     return (
-      <div>
-        <input onInput={this.onInput}></input>
-      </div>
+      <input onInput={this.onInput}></input>
     )
   }
 }
 ```
 
-然后在你的自定义元素上绑定事件：
+然后在自定义元素上绑定事件监听器：
 
+#### Vue
+```html
+<template>
+  <quark-input @custom-event="handler" id="quark-input" />
+</template>
+<script>
+  export default {
+    methods: {
+      handler(e) {
+        console.log(e.detail.value);
+      },
+    },
+  };
+</script>
+```
+
+#### React
 ```tsx
-/**Vue中*/
-<quark-input @input="this.onInput" id="quark-input"/>
+function App() {
+  const handler = (e) => {
+    console.log(e.detail.value);
+  };
+  return <quark-input onCustomEvent={handler} id="quark-input" />;
+}
 ```
 
-或者
+#### Quarkc
+❗不同于Vue，在底层（使用`$emit`时）不支持带有连字符的自定义事件名。
 
+❗与原生事件不同，自定义事件名不会被首字母小写化处理。
 ```tsx
-/**其它任何框架或者无框架中*/
-const myInputElement = document.getElementById("quark-input")
-myInputElement.addEventListener('input', (evt) => {})
+@customElement({ tag: "quark-input-parent", style })
+class QuarkInputParent extends QuarkElement {
+  handler = (e) => {
+    console.log(e.detail.value)
+  }
+
+  render() {
+    // onCustomEvent ❌ 这种情况需要将`CustomEvent`作为$emit的事件名
+    return (
+      <quark-input id="quark-input" oncustomEvent={this.handler} />
+    )
+  }
+}
 ```
- 通过 `this.$emit` 触发自定义事件，`emit` 的第一个参数为事件名，第二个参数为传递的参数。可通过 `evt.detail` 获取到传递的数据。
+
+#### Pure JS
+
+```ts
+const myInputElement = document.getElementById("quark-input")
+myInputElement.addEventListener('customEvent', (e) => {
+  console.log(e.detail.value)
+})
+```

src/docs/watchers_computed.en-US.md

@@ -1 +1,61 @@
 
+
+## Watchers and Computed
+
+### Watchers
+Watching changes of reactive states or properties by `@watch` directive.
+
+```tsx
+@customElement({ tag: "quark-count" })
+class Count extends QuarkElement {
+  @state()
+  count = 0
+
+  handleClick = () => {
+    this.count += 1
+  }
+
+  // * support immediate option, the watcher callback will be triggered immediately after initialization
+  @watch("count", { immediate: false })
+  countLogger(val, oldVal) {
+    console.log(`count from ${oldVal} to ${val}`);
+  }
+
+  render() {
+    return (
+      <button onClick={this.handleClick}>{count}</button>
+    )
+  }
+}
+```
+
+### 计算属性
+Create a new property computed from reactive states or properties by `@computed` directive. Different from normal `getter` methods, computed properties will track the changes of its dependencies and updates automatically. As long as its dependecies are not changed, cached value will be used and no computation will be triggered.
+
+```tsx
+@customElement({ tag: "quark-count" })
+class Count extends QuarkElement {
+  @state()
+  count = 0
+
+  @computed()
+  get doubleCount() {
+    return this.count * 2;
+  }
+
+  handleClick = () => {
+    this.count += 1
+  }
+
+  @watch("doubleCount", { immediate: true })
+  doubleCountLogger(val, oldVal) {
+    console.log(`doubleCount from ${oldVal} to ${val}`);
+  }
+
+  render() {
+    return (
+      <button onClick={this.handleClick}>{doubleCount}</button>
+    )
+  }
+}
+```

src/docs/watchers_computed.zh-CN.md

@@ -1 +1,61 @@
 
+
+## 监视器和计算属性
+
+### 监视器
+通过 `@watch` 监视响应式状态或属性的值的变化。
+
+```tsx
+@customElement({ tag: "quark-count" })
+class Count extends QuarkElement {
+  @state()
+  count = 0
+
+  handleClick = () => {
+    this.count += 1
+  }
+
+  // * 支持指定immediate选项，监视器回调会在初始化时立即触发
+  @watch("count", { immediate: false })
+  countLogger(val, oldVal) {
+    console.log(`count from ${oldVal} to ${val}`);
+  }
+
+  render() {
+    return (
+      <button onClick={this.handleClick}>{count}</button>
+    )
+  }
+}
+```
+
+### 计算属性
+通过 `@computed` 来创建由响应式状态或属性计算出来的新属性。区别于普通`getter`方法，计算属性会自动追踪依赖项的变化，并自动更新。只要依赖项未发生变化，其缓存值会被使用且不会被重新计算。
+
+```tsx
+@customElement({ tag: "quark-count" })
+class Count extends QuarkElement {
+  @state()
+  count = 0
+
+  @computed()
+  get doubleCount() {
+    return this.count * 2;
+  }
+
+  handleClick = () => {
+    this.count += 1
+  }
+
+  @watch("doubleCount", { immediate: true })
+  doubleCountLogger(val, oldVal) {
+    console.log(`doubleCount from ${oldVal} to ${val}`);
+  }
+
+  render() {
+    return (
+      <button onClick={this.handleClick}>{doubleCount}</button>
+    )
+  }
+}
+```