92 lines
4.8 KiB
Markdown
92 lines
4.8 KiB
Markdown
# 设计
|
||
|
||
## 来源与状态
|
||
|
||
- 状态：active
|
||
- 更新日期：2026-08-22
|
||
- 主产品面：`examples/research-shelf.etaf` + `examples/research-shelf.el`
|
||
- HTML 视觉基线：`design/research-shelf.html`
|
||
- 已审查：ETAF View/Component/Data API、`etaf-ui` 的公开组件，以及
|
||
`etaf-sqlite` 的 typed source 合同。
|
||
|
||
## 产品定位
|
||
|
||
Research Shelf 是一个真正有用的本地研究/阅读架：SQLite 保存书籍、论文、
|
||
文章和笔记，用户可以筛选、分页、选择一条记录、更新进度、完成、收藏和归档。
|
||
它不是把 API 名称堆成控制台，而是用一个连贯 workflow 验证 ETAF 的组合能力。
|
||
Playground 默认安装确定性的 256 条 fixture、每页 12 条，用于真实验证分页、DataGrid
|
||
增量更新和 SQLite 查询压力；fixture 数量和 page size 都可以配置。
|
||
|
||
## 结构与分层
|
||
|
||
- Shell：标题/副标题/主题切换 → 三列 workspace → 持久化状态栏。
|
||
- 三列 workspace：筛选栏 / SQLite reading list / selected-item detail inspector。
|
||
- `.etaf`：只保存经过白名单校验的静态结构和文案（section、filter、label）。
|
||
- 同名 `.el`：消费 `.etaf`，组合公开 UI Components，创建 SQLite schema、Data
|
||
Controller、refs、事件处理和生命周期清理。
|
||
- 现有可复用组件：`button`、`checkbox`、`label`、`panel`、`data-grid`、
|
||
`pagination`；应用只负责把它们组合成产品，不复制一套 UI kit。
|
||
|
||
## Playground 框架边界（必须长期遵守）
|
||
|
||
`etaf-playground.el` 是通用 pair playground 框架，不是业务应用模块。
|
||
`etaf-playground-catalog.el` 是独立、可替换的部署目录；业务 pair 的名字、refs
|
||
和验证元数据放在 catalog，不写进 loader 实现。
|
||
|
||
框架只负责：
|
||
|
||
- pair 注册语义和 catalog 读取；
|
||
- `.etaf` 的惰性、inert、白名单读取；
|
||
- 按同名 pair 加载 companion；
|
||
- mount、reset、close，以及测试/GUI 入口。
|
||
|
||
框架绝不负责：业务 Component、数据库包或表结构、palette、业务 state、
|
||
handlers、resources 或应用 refs。它不能 `require etaf-sqlite`，也不能把业务
|
||
组件实现塞进 loader/helper。未来新增例子时，只增加一个同名 `.etaf`/`.el` pair
|
||
和 catalog entry，不改变框架语义。
|
||
|
||
组合和复用是默认设计：优先复用 ETAF/`etaf-ui` 的公开契约，优先拆出清晰的
|
||
Component 边界，避免新增 helper 层或抽象泄漏。
|
||
|
||
## 视觉语言
|
||
|
||
- 气质：editorial、专注、温暖、安静而聪明；避免通用 admin dashboard、KPI
|
||
墙、假图表、彩虹渐变和装饰性噪声。
|
||
- 色彩：ink `#172033`、paper `#F7F3EA`、cobalt `#3657D6`、mint `#3E9B8F`、
|
||
coral `#D86B5D`、amber `#C58A3A`、muted `#6D7482`。
|
||
- 节奏：1 格外部节奏、2 格 panel padding、1 格 workspace gap，控件保持
|
||
intrinsic 宽度；需要分配剩余空间或换行时统一使用 `flex`。
|
||
- 状态：文字和 Unicode 同时表达状态：`⌕`、`★`、`✓`、`◷`、`↗`、`⚠`、`·`。
|
||
- 动效：状态立即可见，不依赖 timer animation，默认支持 reduced motion。
|
||
|
||
## 交互合同
|
||
|
||
- 筛选：All、In progress、Unread、Finished、Starred。
|
||
- 列表：DataGrid 行单选，重复点击可以重新选择；分页按钮在边界处 disabled。
|
||
- 每页行数：激活 `Rows N ✎` 后使用 Emacs 原生 minibuffer 输入 1–100 的整数，
|
||
应用后回到第一页。
|
||
- 详情：`+ 10%`、`✓ Finish`、`☆/★ Star`、`Archive`；完成或 100% 时正确禁用。
|
||
- 存储：成功显示 `✓ Saved locally`，失败保留当前可用内容并提供 Reload。
|
||
- 主题：Light/Dark 由 checkbox 控制；文字、对比度和布局都应保持可读。
|
||
- 键盘：Tab 顺序为筛选 → 行 → 详情动作 → 分页，RET 使用同一组公开 refs。
|
||
|
||
## 响应式与验证
|
||
|
||
- Wide/fullscreen：rail / list / detail 位于同一条 Flex line，呈现三栏。
|
||
- Medium：rail 与 list 保持同排，detail 自动换到下一行。
|
||
- Narrow：同一组三个 Component 按文档顺序自动变为纵向流。
|
||
- Shell 只使用一套带 basis/grow 权重的 wrapping Flex，不读取窗口宽度、不维护
|
||
breakpoint 状态；`row` 只负责紧凑 intrinsic 控件，所有操作控件仍保持独立
|
||
hover/focus 语义。
|
||
- 用 SQLite 临时文件测试 mount/remount、筛选、分页、重复选行、mutation、错误
|
||
状态和 cleanup；GUI 用干净 fullscreen 单窗口截图验证真实布局。
|
||
- 目标：一次 Data mutation 对应一次 Runtime generation/publication；warm 交互
|
||
维持已接受的 105ms p50 预算。
|
||
- 压测入口：`etaf-research-shelf-fixture-size` 默认 256，
|
||
`etaf-research-shelf-page-size` 默认 12；已有本地记录保留，不足部分使用新 ID
|
||
补齐 fixture。
|
||
|
||
## 待 review
|
||
|
||
- [ ] 用户可调整产品命名或 palette；pair 边界、组合/复用原则和公开交互合同不变。
|