feat: add render$ directive

Author: yiludege

packages/.vitepress/config.cn.mts

@@ -32,6 +32,7 @@ export default {
               link: "/cn/useFluth/index.html",
               items: [
                 { text: "to$", link: "/cn/useFluth/to$.html" },
+                { text: "render$", link: "/cn/useFluth/render$.html" },
                 { text: "toComp", link: "/cn/useFluth/toComp.html" },
                 { text: "toComps", link: "/cn/useFluth/toComps.html" },
               ],

packages/.vitepress/config.en.mts

@@ -32,6 +32,7 @@ export default {
               link: "/en/useFluth/index.html",
               items: [
                 { text: "to$", link: "/en/useFluth/to$.html" },
+                { text: "render$", link: "/en/useFluth/render$.html" },
                 { text: "toComp", link: "/en/useFluth/toComp.html" },
                 { text: "toComps", link: "/en/useFluth/toComps.html" },
               ],

packages/core/useFluth/index.ts

@@ -12,6 +12,8 @@ import {
   isRef,
   isReactive,
   toRaw,
+  DirectiveBinding,
+  Directive,
 } from "vue-demi";
 
 export * from "fluth";
@@ -109,6 +111,28 @@ export function to$<T>(
   return stream$;
 }
 
+/**
+ * vue directive, convert stream value to dom element content
+ */
+export const render$: Directive = {
+  mounted(el: HTMLElement, binding: DirectiveBinding) {
+    const stream$ = binding.value;
+    if (!(stream$ instanceof Stream) && !(stream$ instanceof Observable)) {
+      throw new Error("$render only accepts Stream or Observable as input");
+    }
+
+    const observable$ = stream$.thenImmediate((v) => {
+      el.textContent = v?.toString() ?? "";
+    });
+
+    (el as any).__fluth_unsubscribe = () => observable$.unsubscribe();
+  },
+  beforeUnmount(el: HTMLElement) {
+    (el as any).__fluth_unsubscribe?.();
+    (el as any).__fluth_unsubscribe = null;
+  },
+};
+
 /**
  * create stream factory with default plugin
  */

packages/core/useFluth/render$.cn.md

@@ -0,0 +1,81 @@
+# render$ 指令
+
+`render$` 是一个Vue指令，用于将 Stream 或 Observable 的值动态渲染到DOM元素的文本内容中。
+::: info 注意
+采用指令渲染流不会引起组件的更新，只会触发元素的更新，类似于[signals](https://github.com/tc39/proposal-signals)
+:::
+
+## 语法
+
+```vue
+<div v-render$="stream$"></div>
+```
+
+## 示例
+
+### Stream
+
+```vue
+<template>
+  <div>
+    <div v-render$="message$"></div>
+    <button @click="updateMessage">更新消息</button>
+  </div>
+</template>
+
+<script setup>
+import { $, render$ } from "fluth-vue";
+
+const vRender$ = render$;
+
+const message$ = $("Hello World");
+
+const updateMessage = () => {
+  message$.next("消息已更新！");
+};
+</script>
+```
+
+### Observable
+
+```vue
+<template>
+  <div>
+    <div v-render$="processedData$"></div>
+    <button @click="updateData">更新数据</button>
+  </div>
+</template>
+
+<script setup>
+import { $, render$ } from "fluth-vue";
+
+const vRender$ = render$;
+
+const rawData$ = $("原始数据");
+const processedData$ = rawData$.then((data) => `处理后的: ${data}`);
+
+const updateData = () => {
+  rawData$.next("新数据");
+};
+</script>
+```
+
+### 链式操作
+
+```vue
+<template>
+  <!-- ✅ Good performance, only object$.value.attr.name change will trigger re-render -->
+  <div v-render$="object$.pipe(get((v) => v.attr.name))"></div>
+
+  <!-- ❌ bad performance, object$ change will trigger re-render, but attr name change will not -->
+  <div v-render$="object$.then((v) => v.attr.name)"></div>
+</template>
+
+<script setup>
+import { $, get, render$ } from "fluth-vue";
+
+const vRender$ = render$;
+
+const object$ = $({ id: 1, attr: { name: "fluth", age: 18 } });
+</script>
+```

packages/core/useFluth/render$.en.md

@@ -0,0 +1,82 @@
+# render$ Directive
+
+The `render$` directive is a Vue directive that dynamically renders Stream or Observable values to DOM element text content.
+
+::: info Note
+Using the directive to render streams will not trigger component updates, only trigger element updates, similar to [signals](https://github.com/tc39/proposal-signals)
+:::
+
+## Syntax
+
+```vue
+<div v-render$="stream$"></div>
+```
+
+## Examples
+
+### Stream
+
+```vue
+<template>
+  <div>
+    <div v-render$="message$"></div>
+    <button @click="updateMessage">Update Message</button>
+  </div>
+</template>
+
+<script setup>
+import { $, render$ } from "fluth-vue";
+
+const vRender$ = render$;
+
+const message$ = $("Hello World");
+
+const updateMessage = () => {
+  message$.next("Message updated!");
+};
+</script>
+```
+
+### Observable
+
+```vue
+<template>
+  <div>
+    <div v-render$="processedData$"></div>
+    <button @click="updateData">Update Data</button>
+  </div>
+</template>
+
+<script setup>
+import { $, render$ } from "fluth-vue";
+
+const vRender$ = render$;
+
+const rawData$ = $("raw data");
+const processedData$ = rawData$.then((data) => `Processed: ${data}`);
+
+const updateData = () => {
+  rawData$.next("new data");
+};
+</script>
+```
+
+### Chained Operations
+
+```vue
+<template>
+  <!-- ✅ Good performance, only object$.value.attr.name change will trigger re-render -->
+  <div v-render$="object$.pipe(get((v) => v.attr.name))"></div>
+
+  <!-- ❌ bad performance, object$ change will trigger re-render, but attr name change will not -->
+  <div v-render$="object$.then((v) => v.attr.name)"></div>
+</template>
+
+<script setup>
+import { $, get, render$ } from "fluth-vue";
+
+const vRender$ = render$;
+
+const object$ = $({ id: 1, attr: { name: "fluth", age: 18 } });
+</script>
+```