docs: ✏️ 成吨的文档更新, 顺便 dict 优化

README.md

@@ -18,13 +18,15 @@
 # 如何安装
 
 > antd@v4
-` bun i @pro.formily/antd @formily/antd @fomrily/core @formily/react [email protected] @ant-design/icons`
+
+`bun i @pro.formily/antd @formily/antd @fomrily/core @formily/react [email protected] @ant-design/icons`
 
 > antd@v5
-` bun i @pro.formily/antd @formily/antd-v5 @fomrily/core @formily/react [email protected] @ant-design/icons`
+`bun i @pro.formily/antd @formily/antd-v5 @fomrily/core @formily/react [email protected] @ant-design/icons`
 
 > arco.design
-` bun i @pro.formily/arco arco.formily @fomrily/core @formily/react @arco-design/web-react`
+
+`bun i @pro.formily/arco arco.formily @fomrily/core @formily/react @arco-design/web-react`
 
 ## 样式 TODO
 
@@ -37,6 +39,21 @@
 [for/arco.design](https://charlzyx.github.io/pro.formily/arco/)
 
 
+## 如何开发
+
+`bun v4 && bun dev`
+
+```json
+{
+  "scripts": {
+    "dev": "rspress dev",
+    "v4": "bun scripts/switch.ts antd doc",
+    "v5": "bun scripts/switch.ts antd-v5 doc",
+    "arco": "bun scripts/switch.ts arco doc",
+  }
+}
+```
+
 ## powered by
 
 - [@formily](https://formilyjs.org)

docs/components/demos/DictDemo.tsx

@@ -1,6 +1,3 @@
-import { createForm } from "@formily/core";
-import { FormProvider, createSchemaField } from "@formily/react";
-import { Dict, dict, dictEffects, registerDictLoader } from "@pro.formily/antd";
 import {
   Checkbox,
   FormGrid,
@@ -11,6 +8,9 @@ import {
   Select,
   Space,
 } from "@formily/antd";
+import { createForm } from "@formily/core";
+import { FormProvider, createSchemaField } from "@formily/react";
+import { Dict, dict, dictEffects, registerDictLoader } from "@pro.formily/antd";
 import React, { useMemo } from "react";
 
 const loaders = {

docs/components/demos/DictDemo2.tsx

@@ -0,0 +1,63 @@
+import { observer } from "@formily/react";
+import { dict, registerDictLoader } from "@pro.formily/antd";
+import { Button, Space } from "antd";
+
+const loader = registerDictLoader("framework", () => {
+  return Promise.resolve([
+    { label: "vue", value: 0 },
+    { label: "react", value: 1 },
+    { label: "solid", value: 2 },
+  ]);
+});
+
+const LiveDict = observer(() => {
+  const emap = dict.framework?.emap;
+  // console.log("🚀 ~ LiveDict ~ dict:", dict.framework);
+  return (
+    <div>
+      <div
+        onClick={() => {
+          // console.log("🚀 ~ LOG dict:", toJS(dict.framework));
+        }}
+      >
+        LOG
+      </div>
+      <ul>
+        <li>
+          value: {emap?.vue} , label: {emap?.[0]}
+        </li>
+        <li>
+          value: {emap?.react} , label: {emap?.[1]}
+        </li>
+        <li>
+          value: {emap?.solid} , label: {emap?.[2]}
+        </li>
+      </ul>
+    </div>
+  );
+});
+
+const Loader = () => {
+  return (
+    <Button
+      onClick={() =>
+        loader().then((framworks) => {
+          console.log("got it ", framworks);
+        })
+      }
+    >
+      点击加载
+    </Button>
+  );
+};
+
+export default () => {
+  return (
+    <Space>
+      <Loader></Loader>
+      <div>
+        <LiveDict></LiveDict>
+      </div>
+    </Space>
+  );
+};

docs/components/demos/ProArrayTable.tsx

@@ -321,8 +321,8 @@ export default () => {
           <Button
             onClick={() => {
               form.setInitialValues({
-                // array: range(10 * 10000),
-                array: range(10 * 10),
+                array: range(10 * 10000),
+                // array: range(10 * 10),
               });
             }}
           >

docs/components/plus/dict.mdx

@@ -1,5 +1,105 @@
-# Dict
+# 📕 Dict - 远程词典
 
-## 专业词典
-<code src="../demos/DictDemo.tsx"  />
+> Formily 模型中的 `enum` 字段能够满足本地的枚举词典的需求, 但远程的其实更常用一些;
+
+
+## 设计思路
+
+业务中一个常见的场景是，从远程拉取一个 kv 词典列表, 作为 `Select/Checkbox.Group/Radio.Group/` 的 `options` 使用;
+根据对应的 `key` 值获取对应的 `value` 值展示出来, 亦或反向的根据 `value` 取出 `key` 值;
+
+使用基本的归纳演绎法, 可以使用一个约定的数据格式与方式, 将这些类似的场景中使用模式固定下来.
+
+设计一个词典的标准结构约定如下:
+
+```tsx | pure
+export type TDictShape = {
+  // 双向映射表
+  emap: {
+    [x: string]: string | number;
+    [x: number]: string | number;
+  };
+  // 列表形式的存储
+  options: {
+    label: string;
+    value: string | number;
+    key?: string | number;
+    color?: ColorsKey;
+  }[];
+  // on more things~ 因为会在 Tag/Badge 中使用, 额外增加的颜色配置
+  colors: {
+    [x: string]: string;
+    [x: number]: string;
+  };
+};
+```
+
+当然我们并不希望填写这么多属性值, 继续约定一个最基本的原始数据 `label/value`, 其余属性我们都可以转换出来.
+
+```tsx | pure
+type DictLoader = () => Promise<{ label: string, value: string | number, color: string }>
+// 当然, 不可能只有一个词典对不对
+type registerDictLoader = (name: string, loader: DictLoader) => Promise<TDictShape>
+```
+
+## 最终实现
+
+```tsx | pure
+import { registerDictLoader, dict } from '@pro.formily/antd'
+```
+
+约定一个标准的词典加载器 `registerDictLoader`, 根据命名将对应词典注册到内存中的全局缓存;
+
+一个最简单的例子
+
+> color 并不是必填项,  不填写的话，会根据内置的10个颜色顺序读取
+
+```tsx | pure
+// 注册
+const loader = registerDictLoader("bool", () => {
+  return Promise.resolve([
+    { label: "是", value: 1 },
+    { label: "否", value: 0, color: "error" },
+  ]);
+});
+// 与使用
+loader().then(dictshape => console.log(dictshape))
+// or
+dict.bool?.emap
+```
+
+另一个导出 `dict` 是一个全局唯一的 `observeable({})` 值, 结合 `observer`, 我们可以很方便的在组件中使用
+
+### 代码案例: 结合 `observer` 中使用
+
+<code src="../demos/DictDemo2.tsx" />
+
+在 Formily 中使用的话, 我们可以结合 `effect` 和 `schema` 配置,
+```tsx | pure
+import { dictEffects } from '@pro.formily/antd';
+const form = createForm({
+  effects(form) {
+    dictEffects(form)
+  }
+})
+
+const schema = {
+  type: 'string',
+  "x-component": "Select",
+  "x-data": {
+    // 词典名称;
+    dict: "bool",
+    // 默认进行缓存;
+    dictNoCache: false,
+  },
+}
+```
+
+利用 Schema 使用 `x-data` 字段, 添加了词典属性, 在`dictEffects` 中, 惰性加载远程词典, 并注入 `field.dataSource/options` 属性;
+
+额外的, `readPretty` 情况下劫持为优化形态 `Badge/Tag`
+
+## 代码案例: 在 Formily 中使用
+
+<code src="../demos/DictDemo.tsx" />
 

docs/components/plus/linkage.mdx

@@ -1,6 +1,15 @@
-# Linkage
+# 🎹 Linkage - 级联查询
 
-## 高级级联选择
+> 主要为了解决一个很蛋疼的问题, 比如省市区, 返回值如果只有 `code` 的话, 加载不出来 `label`
 
+|属性|说明|类型|默认值|
+|---|---|---|---|
+|`labelInValue`| 增加类比 `<Select />` 的 `labelInValue` 属性和功能支持| `boolean` | `false`|
+|`all`| 懒加载可以加载整棵树的数据 | `boolean` | `false`|
+|`loadData`| 结合 all 属性, 你现在可以加载一整棵树了 | `(opts:{value}[]) => Promise<{ label, value, children?}[]>` | -- |
+
+- 增强: 初始值只有 `value` 的时候, 自动调用接口补全 `label` 展示, 请刷新注意下面两个反显的示意
+
+## 代码案例
 <code src="../demos/Linkage.tsx"  />
 

docs/components/plus/suggestion.mdx

@@ -1,4 +1,7 @@
-# Suggestion
+# 🔎 Suggestion - 联想搜索
+
+> 内部处理了请求竞态, 简化联想搜索的使用
+
+## 代码案例
 
-## 专业搜索建议
 <code src="../demos/Suggestion.tsx"  />

docs/components/pretty/image-view.mdx

@@ -1,3 +1,3 @@
-# 🌌 ImageView - 图片查看
+# 🌟 ImageView - 图片查看
 
 <code src="../demos/ImageView.tsx"  />

docs/components/pro/pro-array-table.mdx

@@ -1,12 +1,62 @@
-# Pro ArrayTable
+# 💡 Pro ArrayTable
 
-|属性|说明|完成情况|
-|---|---|---|
-|`resizeable`| 可拖拽列宽| 🫤 |
-|`settings`|动态列排序|😆 |
-|`RowExpand`|展开列 Schame 支持|😆|
-|`rowSelection`|可选择列, 配置简化|😆|
-|`slice`|分页性能优化|😆|
+> Pro ArrayTable 是一个增强版本的 ArrayTable, 增加了以下属性与功能
+
+- ✅ schema 拓展: RowExpand / Toolbar / Footer
+- ✅ 列配置: 排序与拖动调整列宽
+- ✅ 常用功能配置简化与增强 (pagination/rowSelection/expandable)
+- ✅ `expandable.defaultExpandedAllRows` 现在支持惰性加载啦!
+- ✅ `expandable.expandedRowKeys` / `rowSelection.selectedRowKeys` 现在会根据页码调整进行智能重置!
+
+
+
+## 属性说明
+
+|属性|说明|类型|默认值|
+|----|---|---|---|
+|`resizeable`|可拖拽列宽功能开关, 在 `Columns` 也可以单独设置|`boolean`|`false`|
+|`settings`|动态列排序功能开关| `boolean` | `true`|
+|`slice`|分页性能优化开关, 默认开启| `boolean`| `true`|
+|`rowSelection`|可选列选择功能, 配置简化, 提供功能钩子, 默认关闭| `true\| TableProps['rowSelection']`|--|
+|`pagination`|分页功能, 配置简化, 提供功能钩子, 默认开启, `false` 显式关闭| `false\| TableProps['pagination']`|`{hideOnSingle:true}`|
+|`expandable`|行展开功能, 配置简化, 提供功能钩子配置, 默认关闭| `TableProps['expandable']`|--|
+|`RowExpand`|`Schame`形式的 行展开|--|--|
+|`Toolbar`|`Schame`自定义表头部分内容, 自定义组件名称必须包含 `Toolbar`|--|--|
+|`Footer`|`Schame`自定义表头部分内容, 自定义组件名称必须包含 `Footer` |--|--|
+
+
+## 代码案例
 
-## use Array Table like Pro
 <code src="../demos/ProArrayTable.tsx"  />
+
+### ProArrayTable.useTablePagination 获取分页信息
+
+```tsx | pure
+export interface ITableSelectionContext {
+  current: number;
+  pageSize: number;
+  total: number;
+  setPagination: React.Dispatch<
+    React.SetStateAction<{ current: number; pageSize: number }>
+  >;
+}
+```
+
+### ProArrayTable.useTableExpandable 获取 Expandable 展开行信息
+
+```tsx | pure
+export interface ITableExpandableContext {
+  // 分页页码变更会重置
+  expandedRowKeys: RowKey[];
+  setExpandedRowKeys: React.Dispatch<React.SetStateAction<RowKey[]>>;
+}
+```
+
+### ProArrayTable.useTableRowSelection 获取列选择信息
+
+```tsx | pure
+export interface ITableSelectionContext {
+  selectedRowKeys: RowKey[];
+  setSelectedRowKeys: React.Dispatch<React.SetStateAction<RowKey[]>>;
+}
+```

docs/components/pro/pro-editable.mdx

@@ -1,7 +1,31 @@
-# Pro Editable
+# 💡Pro Editable
 
-## 跟随普通 Object 对象使用
+> ProEditable 是为了解决常见的 `Popconfirm/Modal/Drawer` 弹窗编辑子表单模板代码的问题
+
+### 为什么不是 FormDialog/FormDrawer ?
+
+~~没有人比我更懂formily 👐~~
+这两个都是方法调用, 不能用 json 描述出来所以 `FormDialog/FormDrawer` 适合用于更灵活的场景;
+此外, `FormDialog/FormDrawer` 内部是使用了 [document.body.appendChild](https://github.com/alibaba/formily/blob/formily_next/packages/antd/src/form-drawer/index.tsx#L122) 凭空创建了一个新的
+dom 节点来承载这个表单, 脱离了 root 节点, 所以需要用 Portals 打补丁来解决,
+但使用中会仍会遇到需要单独配置 ConfigProvider 等其他一些奇奇怪怪的问题.~~就很烦 🪃~~
+
+## 设计思路
+
+ProEditable 灵感来自 `Editable` 既然单独字段能编辑, 那么, 子对象字段是不是也应该能够编辑 ?
+这种场景不要太多: 比如表格行内容编辑; 此时, 这篇[标准化CRUD作用域变量规范
+](https://github.com/alibaba/formily/discussions/3207) 直指 formily 模型抽象核心的内容就尤为重要, 这里面提到的 `record` 模型是如此的重要;
+以至于在 `2.2.19` 版本中, `record` 被作为 `Field` 模型的核心属性, 直接追加到了 `BaseField` 上.
+关联文档: [RecordScope](https://react.formilyjs.org/zh-CN/api/components/record-scope)
+
+
+在这个基础之上, 那 ProEditable 就顺利成章的消费 `field.record` 的数据, 在不影响当前表单响应模型的基础上;
+使用 ProEditable 所在 `field` 上的属性与 `form` 上共享的组件与属性, 创建一个子表单, 供给弹窗消费;
+
+### 代码案例: 在普通 Object 对象跟随使用
 <code src="../demos/ProEditable.tsx"  />
 
-## 在列表中使用
+更常见的
+
+### 代码案例: 在列表中使用
 <code src="../demos/ProEditableWithArray.tsx"  />