From a8d57e4d1350be9aa6246a19a7f085c7e99ec3a4 Mon Sep 17 00:00:00 2001
From: Viki <hi@viki.moe>
Date: Mon, 19 Aug 2024 11:14:58 +0800
Subject: [PATCH] docs: add roadmap

---
 docs/docs/en/roadmap/index.md    | 34 ++++++++++++++++++++++++++++++++
 docs/docs/zh-cn/roadmap/index.md | 29 ++++++++++++++++++++++++++-
 docs/locale.ts                   |  8 ++++++++
 3 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 docs/docs/en/roadmap/index.md

diff --git a/docs/docs/en/roadmap/index.md b/docs/docs/en/roadmap/index.md
new file mode 100644
index 00000000..40ea64ed
--- /dev/null
+++ b/docs/docs/en/roadmap/index.md
@@ -0,0 +1,34 @@
+# Roadmap
+
+## v1 Version (Current Version) \{#v1-version}
+
+> The functionalities are basically complete. Future work will focus on iterations over existing hooks, bug fixes, and ecosystem expansion.
+
+### Automatic Dependency Collection \{#automatic-dependency-collection}
+
+Migrating more hooks to use the **Automatic Dependency Collection** scheme. This is transparent to users but can significantly reduce unnecessary renders. For details, see [Dependency Collection](/docs/features/dependencies-collection).
+
+## v2 Version \{#v2-version}
+
+Improvements and optimizations will be made to address the issues and shortcomings of the current v1 version, which will introduce breaking changes:
+
+### Adjust `useSupported` \{#adjust-use-supported}
+
+Adjust the API return to expose the `isSupported` attribute as an object, enabling the Automatic Dependency Collection scheme. At the same time, force the user to explicitly specify a fallback function for "when the browser does not support the feature," aiming to explicitly remind developers to handle potential compatibility problems and reduce the likelihood of misuse.
+
+> All internal hooks that depend on `useSupported` will be adjusted to fit the new API return format.
+
+```tsx
+// === Before Changing (v1) ===
+const isSupported = useSupported(() => 'IntersectionObserver' in window)
+console.log(isSupported) // true
+
+// === After Changing (v2) ===
+const { isSupported } = useSupported(() => 'IntersectionObserver' in window, {
+  // onUnsupported must be explicitly specified
+  onUnsupported: () => {
+    console.log('IntersectionObserver is unsupported.')
+  }
+})
+console.log(isSupported) // true
+```
diff --git a/docs/docs/zh-cn/roadmap/index.md b/docs/docs/zh-cn/roadmap/index.md
index 8679795c..884a82f7 100644
--- a/docs/docs/zh-cn/roadmap/index.md
+++ b/docs/docs/zh-cn/roadmap/index.md
@@ -1,7 +1,34 @@
 # 后期规划（Roadmap）
 
+## v1 版本（当前版本） \{#v1-version}
 
+> 功能已基本完善，后期主要针对现有 Hooks 进行功能迭代、问题修复和生态扩充。
 
-## V1（当前版本）
+### 自动依赖收集 \{#automatic-dependency-collection}
 
+迁移更多 Hooks 以使用**自动依赖收集**方案。对用户使用无感，但能显著降低不必要的渲染，详情参考 [依赖收集](/docs/features/dependencies-collection)。
 
+## v2 版本 \{#v2-version}
+
+针对当前 v1 版本的问题和不足进行改进优化，会引入破坏性变更：
+
+### 调整 `useSupported` \{#adjustments-to-use-supported}
+
+调整 API 返回，以对象的形式暴露 `isSupported` 属性，以启用自动依赖收集方案。同时，在 API 层面强制用户显式指定「当浏览器不支持该特性时的」回退处理函数，这一更改旨在显式提醒开发者处理可能存在的兼容性问题，以降低错误使用的可能性。
+
+> 将会对所有内部依赖 `useSupported` 的 Hooks 进行调整，以适配新的 API 返回形式。
+
+```tsx
+// === 更改前 (v1) ===
+const isSupported = useSupported(() => 'IntersectionObserver' in window)
+console.log(isSupported) // true
+
+// === 更改后 (v2) ===
+const { isSupported } = useSupported(() => 'IntersectionObserver' in window, {
+  // onUnsupported 必须显式指定
+  onUnsupported: () => {
+    console.log('IntersectionObserver is unsupported.')
+  }
+})
+console.log(isSupported) // true
+```
diff --git a/docs/locale.ts b/docs/locale.ts
index 0faf93f6..1d3585b2 100644
--- a/docs/locale.ts
+++ b/docs/locale.ts
@@ -146,6 +146,10 @@ export const navbar = {
       text: 'Reference',
       link: '/reference',
     },
+    {
+      text: 'Roadmap',
+      link: '/roadmap',
+    },
     {
       text: `v${version}`,
       items: [
@@ -174,6 +178,10 @@ export const navbar = {
       text: 'Hooks 列表',
       link: `/${langSlug.zhCN}/reference`,
     },
+    {
+      text: '后期规划',
+      link: `/${langSlug.zhCN}/roadmap`,
+    },
     {
       text: `v${version}`,
       items: [