create-yoya-ui 0.4.1 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yoya-ui",
-  "version": "0.4.1",
+  "version": "0.6.1",
   "description": "Scaffold a new yoya-ui project with Vite: basic template (SPA) or SSR template (renderPage + hydrateOrMount).",
   "type": "module",
   "bin": {

package/templates/admin/RULES.md

@@ -24,6 +24,7 @@ src/
 - 页面：`<名字>-page.js`（`member-list-page.js`、`todo-approval-page.js`）
 - 组件：PascalCase（`AdminShell`、`MemberTable`）
 - 共享 UI 类别文件：`ui.<类别>.js`（`ui.buttons.js`、`ui.pages.js`）
+- 共享纯状态工具：`state.<类别>.js`（`state.rows.js` 的行合并与字段读取）
 
 ## 3. api 分层
 
@@ -31,8 +32,8 @@ src/
 
 - `mgr.js`：本域管理请求命令（增删改查等）
 - `req.js`：对外能力入口（其他模块 / 共享组件调用本域时使用）
-- `views.js`：领域结果结构（纯数据类），由命令的 `toItem / toDetail` 映射
-- `state.js`：状态类，持有数据与筛选，`subscribe(listener)` 通知视图更新
+- `views.js`：领域结果结构（纯数据类），由命令的 `toItem / toDetail` 映射；**字段按热度分**——行内展示且会变的字段用 `ref` 句柄，key 与不参与原地刷新的字段保持普通值，并提供 `apply(row)` 原地合并
+- `state.js`：状态类，持有数据与筛选；**要驱动视图的字段用 `ref` 持有**（写入即完成通知），`subscribe(listener)` 只留给非视图副作用（埋点 / 持久化）
 - `mock.js`：演示用内存 mock（接入真实后端后删除）
 
 判据：有管理动作用 `mgr.js`；只提供查询给外部用 `req.js`；两者可并存（如 `member.mgr.js` + `member.req.js`）。
@@ -56,6 +57,7 @@ export default {
 ## 5. 共享组件
 
 - **通用 UI**（无业务语义）：放 `shared/ui.<类别>.js`
+- **纯状态工具**（无 UI）：放 `shared/state.<类别>.js`，如 `state.rows.js` 的 `mergeRowsByKey()` / `fieldValue()`
 - **业务共享组件**（带业务语义且多模块使用）：放 `shared/<组件>/` 自包含子目录（组件 + 状态 + 文案），对外只暴露工厂
 - **数据获取走 req.js**：共享组件需要业务数据时调用所属域 `api/<域>.req.js` 的公开能力（如 `MemberReq.QueryAvailable().submit()`），不自造数据请求、不注入数据源
 - **不深层 import**：只允许跨模块引用 `req.js`，不 import 业务域的 pages / components / state 内部实现
@@ -67,17 +69,21 @@ export default {
 ## 6. 外壳与导航状态
 
 - `ShellState` 是导航状态（当前模块 / 当前路径）的**唯一事实源**，持有 router，暴露 `switchModule(module)` / `navigate(path)`
-- 路由订阅驱动同步：`router.subscribe → state.syncFromPath(path)`，状态变化时通知订阅者
-- 顶栏 / 侧栏从状态**派生高亮**，组件不持有自己的激活状态
-- `AdminShell` 只做装配：布局组装 + 状态接线，不直接操作 router
-- 组件统一写法：节点在 `render()` 内声明式构建，内部引用（如 sidebar 实例、items Map）只用于动态更新
-- 前进 / 后退、同模块内切换路由的高亮同步由状态管道自动完成，不需要手动调用
+- 导航字段（`menus` / `activeModuleKey` / `activePath`）是 `ref`：`router.subscribe → state.syncFromPath(path)` 只把路径写回信号
+- 顶栏 / 侧栏从状态**派生高亮**：菜单区先 `rebuildable()` 再读信号（模块 / 路径变化自动重建），组件不持有自己的激活状态
+- `AdminShell` 只做装配：布局组装，不直接操作 router，也不需要订阅回调转发
+- 组件统一写法：节点在 `render()` 内声明式构建，不保留 `applyState()` 这类手动同步入口；没有额外行为要定义（无内部状态、无对外命令方法）的组件直接返回 ViewNode 即可，不必包一层 `render()`
+- 组件需要对外命令方法时用 `vNode((api) => 视图)`：命令收到 `api` 上（`api.reload = () => { …; return api }`），工厂挂到返回的节点并校验重名；自带边界写 `api.whenFailed`，其余节点级能力（`mountable()` / `rebuildable()`）链在节点上
 
 ## 7. 页面规则
 
 - **简单 / 占位页**：只放 `pages/<页面>-page.js`，可复用 `shared/ui.pages.js` 的 `PlaceholderPage`
 - **有数据交互的页面**：展开完整模块（api / components / pages / utils）
-- 页面只做编排：组合子组件、绑定事件、调用 state 动作，不写请求逻辑
+- **页面只做编排**：组合子组件、绑定事件、调用 state 动作，不写请求逻辑
+- **状态到位即刷新**：表格 / 文本绑句柄（`rows: state.items`、`vText(handle)`），动作里写 ref 就完成更新；不要写 `state.subscribe(() => table.refresh())`
+- **列表按 key 对账**：表格 `tbody.keyed(rows, (row) => row.id, buildRow)`，行模型刷新走 `mergeRowsByKey()`（复用实例 → 不重建行），行内热字段句柄只刷自己那一格
+- **命令式组件由动作同步**：`vPagination` / `vTree` 这类逐次调用的组件不是信号感知的，数据到位后在动作里 `pagination.update({...})` / `tree.nodes(...)` 同步一次
+- **行模型传入弹窗要读值**：弹窗回填用 `fieldValue(row.name)`，它同时吃句柄（行模型）与普通值（裸行）
 
 ## 8. mock 与数据接入
 
@@ -108,7 +114,14 @@ export default {
 
 ## 12. 权限接入
 
-- **会话与权限**：会话请求命令并入 `shell.req.js`（`ShellReq.Me()`），`shell/api/auth.mock.js` 提供 `/auth/me` 演示数据；会话状态融合进 `ShellState`（`user()` / `roles()` / `permissions()`），`loadSession()` 内 `installAccess` 注入全局。
+- **会话与权限**：会话请求命令并入 `shell.req.js`（`ShellReq.Me()`），`shell/api/auth.mock.js` 提供 `/auth/me` 演示数据；会话状态融合进 `ShellState`（普通字段 `user` / `roles` / `permissions`，不参与渲染），`loadSession()` 内 `installAccess` 注入全局。
 - **菜单 / 路由**：`shell.mock.js` 的每条路由声明 `permCode`（与权限管理页的 code 对齐），`ShellState.load()` 按 `currentAccess().canRead(permCode)` 过滤菜单；无读的路由不注册，直达 URL 落到未找到页。
 - **按钮 / 操作**：直接在按钮上声明 `.access('system:member:create')` 等裸码，无写权限自动禁用、无读自动隐藏（见 member-toolbar / member-table）。
 - **体验层**：前端只做显隐 / 禁用，真正的拦截必须由后端按权限码校验。
+
+## 13. 节点写法（易错点）
+
+- **没有节点级 `text()`**：追加文本用 `child(content)`；反复替换同一处文本留一个 `vText()` 句柄用 `textContent(next)`；组件自带的 `text()` 与 SVG `<text>` 的 `text()` 不受影响
+- **非必要不提前建节点**：只有需要组件句柄（`refresh()` / `update()` / `open()` 等对外命令方法）时才在 `render()` 外先建再 `child()` 挂载；纯结构节点在 `render()` 里就地组合，不要先存成中间变量再挂回去
+- **句柄进组件 props 要包节点**：`vTd(vText(handle))`、`cell.child(handle)` 建立绑定；`vTd(handle)` 会被当成无效 setup 丢掉
+- **值位置直接接句柄**：`attr('data-count', count)`、`vText(count)`；`count.value` 是快照，写完不再更新

package/templates/admin/package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@yoyaflow/yoya-ui": "^0.4.0"
+    "@yoyaflow/yoya-ui": "^0.6.1"
   },
   "devDependencies": {
     "typescript": "^7.0.2",

package/templates/admin/src/api/domain.api.d.ts

@@ -1,5 +1,5 @@
 /** 领域请求入口类型声明（对应 domain.api.js）。 */
-import type { RequestCommand } from '@yoyaflow/yoya-ui';
+import type { RequestCommand } from '@yoyaflow/yoya-ui/api';
 
 export function mockRequest(
   method: string,

package/templates/admin/src/api/domain.api.js

@@ -1,5 +1,5 @@
 // 领域请求入口：统一 Result 解析 + mock / 真实传输切换。
-import { configureRequest, Result } from '@yoyaflow/yoya-ui';
+import { configureRequest, Result } from '@yoyaflow/yoya-ui/api';
 import { fetchSubmit } from './fetch.api.js';
 
 const mockHandlers = new Map();

package/templates/admin/src/api/fetch.api.d.ts

@@ -1,4 +1,4 @@
 /** 原始传输层类型声明（对应 fetch.api.js）。 */
-import type { RequestCommand } from '@yoyaflow/yoya-ui';
+import type { RequestCommand } from '@yoyaflow/yoya-ui/api';
 
 export function fetchSubmit(req: RequestCommand): Promise<unknown>;

package/templates/admin/src/features/dashboard/overview/pages/dashboard-overview-page.js

@@ -144,7 +144,7 @@ export function DashboardOverviewPage() {
                       color: 'var(--yoya-color-text-muted, #64748b)',
                       fontSize: '12px'
                     });
-                    text.text('CPU 使用率');
+                    text.child('CPU 使用率');
                   });
                 });
                 row.div((box) => {
@@ -155,7 +155,7 @@ export function DashboardOverviewPage() {
                       color: 'var(--yoya-color-text-muted, #64748b)',
                       fontSize: '12px'
                     });
-                    text.text('内存使用率');
+                    text.child('内存使用率');
                   });
                 });
               });

package/templates/admin/src/features/system/dicts/api/dict.mgr.d.ts

@@ -1,5 +1,5 @@
 /** 字典管理请求命令类型声明（对应 dict.mgr.js）。 */
-import { RequestBase } from '@yoyaflow/yoya-ui';
+import { RequestBase } from '@yoyaflow/yoya-ui/api';
 import Dicts, { DictStatus } from './dict.views.js';
 
 type DictTypeInstance = InstanceType<typeof Dicts.DictTypeItem>;

package/templates/admin/src/features/system/dicts/api/dict.mgr.js

@@ -1,5 +1,5 @@
 // 字典管理请求命令：字典类型与字典项。
-import { RequestBase } from '@yoyaflow/yoya-ui';
+import { RequestBase } from '@yoyaflow/yoya-ui/api';
 import Dicts from './dict.views.js';
 
 class QueryTypes extends RequestBase {

package/templates/admin/src/features/system/dicts/api/dict.state.d.ts

@@ -1,4 +1,6 @@
 /** 字典页状态类类型声明（对应 dict.state.js）。 */
+import type { SignalHandle } from '@yoyaflow/yoya-ui';
+import type { Result } from '@yoyaflow/yoya-ui/api';
 import Dicts from './dict.views.js';
 
 type DictTypeInstance = InstanceType<typeof Dicts.DictTypeItem>;
@@ -6,19 +8,20 @@ type DictItemInstance = InstanceType<typeof Dicts.DictItem>;
 
 export default class DictsPageState {
   constructor();
-  types(): DictTypeInstance[];
-  selectedTypeId(): number | null;
-  selectedType(): DictTypeInstance | null;
-  items(): DictItemInstance[];
-  page(): number;
-  pageSize(): number;
-  total(): number;
+  /** 视图字段：表格 / 弹窗直接绑句柄，写入即更新 */
+  types: SignalHandle<DictTypeInstance[]>;
+  items: SignalHandle<DictItemInstance[]>;
+  selectedTypeId: SignalHandle<number | null>;
+  page: SignalHandle<number>;
+  pageSize: SignalHandle<number>;
+  total: SignalHandle<number>;
+  /** 派生值：当前选中的字典类型 */
+  selectedType: SignalHandle<DictTypeInstance | null>;
   setPage(value: number): void;
   setPageSize(value: number): void;
-  subscribe(listener: () => void): () => void;
-  loadTypes(): Promise<unknown>;
-  selectType(id: number): void;
-  loadItems(): Promise<void>;
+  loadTypes(): Promise<Result<DictTypeInstance[]>>;
+  selectType(id: number | null): Promise<this>;
+  loadItems(): Promise<DictItemInstance[]>;
   addType(payload: Record<string, unknown>): Promise<Record<string, unknown>>;
   editType(id: number, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
   removeType(id: number): Promise<void>;

package/templates/admin/src/features/system/dicts/api/dict.state.js

@@ -1,92 +1,64 @@
-// 字典页状态类：字典类型 + 当前类型下的字典项。
+// 字典页状态类：字典类型 + 当前类型下的字典值。视图字段都用 ref 持有，
+// 动作写句柄即完成通知——表格绑句柄，页面与弹窗都不需要手动重建。
+import { computed, ref } from '@yoyaflow/yoya-ui';
+import { mergeRowsByKey } from '../../../../shared/state.rows.js';
 import DictMgr from './dict.mgr.js';
 
 export default class DictsPageState {
   constructor() {
-    this._types = [];
-    this._selectedTypeId = null;
-    this._items = [];
-    this._page = 1;
-    this._pageSize = 10;
-    this._total = 0;
-    this._listeners = new Set();
-  }
-
-  types() {
-    return this._types;
-  }
-
-  selectedTypeId() {
-    return this._selectedTypeId;
-  }
-
-  selectedType() {
-    return this._types.find((type) => type.id === this._selectedTypeId) ?? null;
-  }
-
-  items() {
-    return this._items;
-  }
-
-  page() {
-    return this._page;
-  }
-
-  pageSize() {
-    return this._pageSize;
-  }
-
-  total() {
-    return this._total;
+    this.types = ref([]);
+    this.items = ref([]);
+    this.selectedTypeId = ref(null);
+    this.page = ref(1);
+    this.pageSize = ref(10);
+    this.total = ref(0);
+    // 派生值：当前选中的字典类型（多信号组合用 computed）
+    this.selectedType = computed(
+      () => this.types.value.find((type) => type.id === this.selectedTypeId.value) ?? null
+    );
   }
 
   setPage(value) {
-    this._page = Math.max(1, Number(value) || 1);
+    this.page.value = Math.max(1, Number(value) || 1);
   }
 
   setPageSize(value) {
-    this._pageSize = Math.max(1, Number(value) || 10);
-  }
-
-  subscribe(listener) {
-    this._listeners.add(listener);
-    return () => this._listeners.delete(listener);
+    this.pageSize.value = Math.max(1, Number(value) || 10);
   }
 
   async loadTypes() {
     const result = await DictMgr.QueryTypes({
-      page: this._page,
-      pageSize: this._pageSize
+      page: this.page.value,
+      pageSize: this.pageSize.value
     }).submit();
-    this._types = result.data;
-    this._total = result.total;
-    if (!this._selectedTypeId && this._types.length > 0) {
-      this._selectedTypeId = this._types[0].id;
+    this.types.value = mergeRowsByKey(this.types.peek(), result.data);
+    this.total.value = result.total;
+    if (!this.selectedTypeId.value && this.types.peek().length > 0) {
+      this.selectedTypeId.value = this.types.peek()[0].id;
     }
     await this.loadItems();
-    this._emit();
     return result;
   }
 
   async selectType(id) {
-    this._selectedTypeId = id;
+    this.selectedTypeId.value = id;
     await this.loadItems();
-    this._emit();
     return this;
   }
 
   async loadItems() {
-    if (this._selectedTypeId === null) {
-      this._items = [];
-      return;
+    if (this.selectedTypeId.value === null) {
+      this.items.value = [];
+      return [];
     }
-    const result = await DictMgr.QueryItems({ typeId: this._selectedTypeId }).submit();
-    this._items = result.data;
+    const result = await DictMgr.QueryItems({ typeId: this.selectedTypeId.value }).submit();
+    this.items.value = mergeRowsByKey(this.items.peek(), result.data);
+    return this.items.value;
   }
 
   async addType(payload) {
     await DictMgr.CreateType(payload).submit();
-    this._page = 1;
+    this.page.value = 1;
     await this.loadTypes();
     return payload;
   }
@@ -99,36 +71,29 @@ export default class DictsPageState {
 
   async removeType(id) {
     await DictMgr.RemoveType({ id }).submit();
-    if (this._selectedTypeId === id) {
-      this._selectedTypeId = null;
+    if (this.selectedTypeId.value === id) {
+      this.selectedTypeId.value = null;
     }
-    if (this._types.length === 1 && this._page > 1) {
-      this._page -= 1;
+    if (this.types.peek().length === 1 && this.page.value > 1) {
+      this.page.value -= 1;
     }
     await this.loadTypes();
   }
 
   async addItem(payload) {
-    await DictMgr.CreateItem({ typeId: this._selectedTypeId, ...payload }).submit();
+    await DictMgr.CreateItem({ typeId: this.selectedTypeId.value, ...payload }).submit();
     await this.loadItems();
-    this._emit();
     return payload;
   }
 
   async editItem(id, payload) {
     await DictMgr.UpdateItem({ id, ...payload }).submit();
     await this.loadItems();
-    this._emit();
     return payload;
   }
 
   async removeItem(id) {
     await DictMgr.RemoveItem({ id }).submit();
     await this.loadItems();
-    this._emit();
-  }
-
-  _emit() {
-    this._listeners.forEach((listener) => listener());
   }
 }

package/templates/admin/src/features/system/dicts/api/dict.views.d.ts

@@ -1,36 +1,49 @@
 /** 字典结果结构类型声明（对应 dict.views.js）。 */
+import type { SignalHandle } from '@yoyaflow/yoya-ui';
+
+/** 字典状态：与 utils/options.js 的 statusOptions 对齐 */
 export type DictStatus = 'active' | 'disabled';
 
+export type DictTypeRow = {
+  id: number;
+  name?: string;
+  code?: string;
+  status?: DictStatus;
+  remark?: string;
+};
+
+export type DictItemRow = {
+  id: number;
+  typeId?: number | null;
+  label?: string;
+  value?: string;
+  sort?: number;
+  status?: DictStatus;
+};
+
 export class DictTypeItem {
+  /** key：普通值，不能是句柄 */
   id: number;
-  name: string;
-  code: string;
-  status: DictStatus;
-  remark: string;
-  constructor(init?: {
-    id: number;
-    name?: string;
-    code?: string;
-    status?: DictStatus;
-    remark?: string;
-  });
+  /** 行内热字段：句柄写入即刷新对应单元格 */
+  name: SignalHandle<string>;
+  code: SignalHandle<string>;
+  status: SignalHandle<string>;
+  remark: SignalHandle<string>;
+  constructor(row?: DictTypeRow);
+  apply(row: DictTypeRow): this;
 }
 
 export class DictItem {
+  /** key：普通值，不能是句柄 */
   id: number;
+  /** 关系字段：不参与原地刷新 */
   typeId: number | null;
-  label: string;
-  value: string;
-  sort: number;
-  status: DictStatus;
-  constructor(init?: {
-    id: number;
-    typeId?: number | null;
-    label?: string;
-    value?: string;
-    sort?: number;
-    status?: DictStatus;
-  });
+  label: SignalHandle<string>;
+  value: SignalHandle<string>;
+  sort: SignalHandle<number>;
+  status: SignalHandle<string>;
+  constructor(row?: DictItemRow);
+  apply(row: DictItemRow): this;
 }
 
 declare const Dicts: {

package/templates/admin/src/features/system/dicts/api/dict.views.js

@@ -1,22 +1,44 @@
-// 字典结果结构（纯数据）。
+// 字典结果结构（纯数据）：行内展示且会原地变化的字段用句柄，
+// key 与不参与原地刷新的字段（如关系字段）保持普通值。
+import { ref } from '@yoyaflow/yoya-ui';
+import { fieldValue } from '../../../../shared/state.rows.js';
+
 class DictTypeItem {
-  constructor({ id, name = '', code = '', status = 'active', remark = '' } = {}) {
-    this.id = id;
-    this.name = name;
-    this.code = code;
-    this.status = status;
-    this.remark = remark;
+  constructor(row = {}) {
+    this.id = row.id; // key：普通值，不能是句柄
+    this.name = ref(fieldValue(row.name) ?? '');
+    this.code = ref(fieldValue(row.code) ?? '');
+    this.status = ref(fieldValue(row.status) ?? 'active');
+    this.remark = ref(fieldValue(row.remark) ?? '');
+  }
+
+  /** 合并而非重建：实例身份不变，keyed 复用行节点，只刷句柄绑定的位置。 */
+  apply(row) {
+    this.name.value = fieldValue(row.name) ?? '';
+    this.code.value = fieldValue(row.code) ?? '';
+    this.status.value = fieldValue(row.status) ?? 'active';
+    this.remark.value = fieldValue(row.remark) ?? '';
+    return this;
   }
 }
 
 class DictItem {
-  constructor({ id, typeId = null, label = '', value = '', sort = 0, status = 'active' } = {}) {
-    this.id = id;
-    this.typeId = typeId;
-    this.label = label;
-    this.value = value;
-    this.sort = sort;
-    this.status = status;
+  constructor(row = {}) {
+    this.id = row.id; // key：普通值，不能是句柄
+    this.typeId = fieldValue(row.typeId) ?? null; // 关系字段：不参与原地刷新
+    this.label = ref(fieldValue(row.label) ?? '');
+    this.value = ref(fieldValue(row.value) ?? '');
+    this.sort = ref(fieldValue(row.sort) ?? 0);
+    this.status = ref(fieldValue(row.status) ?? 'active');
+  }
+
+  apply(row) {
+    this.typeId = fieldValue(row.typeId) ?? this.typeId;
+    this.label.value = fieldValue(row.label) ?? '';
+    this.value.value = fieldValue(row.value) ?? '';
+    this.sort.value = fieldValue(row.sort) ?? 0;
+    this.status.value = fieldValue(row.status) ?? 'active';
+    return this;
   }
 }