web/base
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fixed virtual list scrolling issues by removing reactive padding bindings and optimizing hidden element height measurement. By: AICoder

Browse Source
This commit is contained in:
AI Engineer 2026-06-05 20:05:26 +08:00
parent 48eb3e1311
commit 5f286185ae
19 changed files with 7576 additions and 816 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

372
CAPABILITY.md Normal file
View File

@ -0,0 +1,372 @@
# @apigo.cc/base 能力清单 (Capability Specification)
<!-- section: header -->
## 一、 全局导出与生命周期行为
### 1. 导出与全局挂载
- **模块导出**：`index.js` 重新导出了 `http.js`, `ui.js`, `form.js`, `controls.js`, `list.js`, `nav.js`, `interaction.js` 中的所有对象，以及来自 `@apigo.cc/state` 的 `State`。
- **全局命名空间挂载**：在 `window/globalThis` 上挂载了 `HTTP`, `UI`, `AutoForm`, `MouseMover`, `VirtualScroll`, `ApigoBase`。
- **初始化自动刷新**：页面加载时（`DOMContentLoaded` 或立即执行），对 `document.documentElement` 执行 `RefreshState()`。
### 2. 退出拦截逻辑
- **拦截触发条件**：当 `State.exitBlocks > 0` 时，通过 `window.addEventListener('beforeunload')` 拦截页面刷新或关闭（调用 `event.preventDefault()`）。
### 3. 主题自动适配
- **逻辑行为**：若 `<html>` 元素上既没有 `data-bs-theme` 也没有 `$data-bs-theme`，则自动注入属性：
`$data-bs-theme="LocalStorage.darkMode?'dark':'light'"`。
<!-- endsection: header -->
---
<!-- section: http -->
## 二、 HTTP 请求引擎 (`HTTP`)
### 1. 核心方法
- **`HTTP.request(options)`** (异步)
- **参数类型**：`options: Object`
- `url` (String, 必填): 请求地址。
- `method` (String, 可选): 默认 `'POST'`。会内部自动转为大写。
- `data` (Any, 可选): 请求载荷。
- `headers` (Object, 可选): 默认 `{}`。
- `responseType` (String, 可选): `'json' | 'binary' | 'text'`。若未提供，将根据响应头 `Content-Type` 自动解析（含 `application/json` 解析为 `'json'`，匹配图片/音视频/zip/pdf等解析为 `'binary'`，其余解析为 `'text'`）。
- `timeout` (Number, 可选): 默认 `10000` (ms)。基于 `AbortSignal.timeout` 实现。
- **请求载荷 (`data`) 自动处理逻辑**：
- 若 `data` 为 `HTMLFormElement`，内部自动转换为 `FormData`。
- 若 `data` 为普通对象，且其属性中包含 `File`, `Blob`, `FileList` 实例，内部自动转换为 `FormData`。其中，`FileList` 或 `Array` 属性会依次 append 到相同 key 下，排除 `undefined` / `null`。
- 若数据最终为 `FormData`，则 **自动删除** `headers['Content-Type']`（由浏览器自动设置 boundary）。
- 若数据为普通对象且非二进制，且 `headers` 中无 `Content-Type`，则序列化为 JSON 字符串并自动添加 `headers['Content-Type'] = 'application/json'`。
- **返回值**：`Promise<ResponseObject>`，其结构为：
```javascript
{
ok: Boolean, // 请求是否成功 (status 在 200-299)
status: Number, // HTTP 状态码
headers: Object, // 响应头键值对
responseType: String, // 实际解析后的响应类型 ('json' | 'binary' | 'text')
result: Any, // 响应数据主体
error: String | null // 错误信息 (若请求失败或 ok === false)
}
```
- **快捷方法** (内部包装 `HTTP.request`)：
- `HTTP.get({ url, ...opt })`
- `HTTP.post({ url, data, ...opt })`
- `HTTP.put({ url, data, ...opt })`
- `HTTP.delete({ url, ...opt })`
- `HTTP.head({ url, ...opt })`
<!-- endsection: http -->
---
<!-- section: api -->
## 三、 声明式数据组件 (`<API>`)
### 1. 响应式状态模型 (`State`)
- **`request`** (读写): 映射请求参数。结构与 `HTTP.request` 参数一致：
`{ url: '', method: 'GET', headers: {}, data: null, timeout: 10000, responseType: '' }`
- **`response`** (读写): 包含当前请求执行结果。结构为：
`{ loading: false, ok: null, status: null, error: null, headers: {}, responseType: '', result: null }`
- **`result`** (读写): 响应结果快捷引用。当 `response.result` 为对象时，底层通过 `Object.assign` 合并更新；否则直接覆盖。
### 2. 编程接口方法 (`Methods`)
- **`do(opt = {})`**
- **用途**：手动执行请求。
- **参数**：`opt` 对象的字段（如 `headers`, `data` 等）会与 `request` 属性合并。
- **控制参数**：`opt.noui` (Boolean)。若为 `true`，则在请求失败时不自动调用 `UI.toast` 弹窗。
- **返回值**：`Promise<ResponseObject>`。若请求失败或接口返回 `{ error: ... }`，Promise 会抛出异常（reject）。
### 3. 特殊逻辑行为
- **`auto` (Attribute)**：
若组件含有 `auto` 属性，且 `request.url` 非空，则深度监听 `request` 对象的变化。一旦变化，会在下一微任务队列（Promise.resolve()）自动、异步触发 `do()`。有防抖机制，避免同一周期多次触发。
### 4. 事件派发
- **`response`**：请求成功时触发。
- `bubbles`: `false`
- `cancelable`: `false`
- `detail`: 完整的 `ResponseObject` 对象。
- **`error`**：请求失败（网络错误、非2xx状态码、或返回数据中含 `error` 字段）时触发。
- `bubbles`: `true`
- `cancelable`: `false`
- `detail`: Error 对象。
<!-- endsection: api -->
---
<!-- section: form -->
## 四、 万能表单系统 (`<AutoForm>`)
### 1. 容器属性 (Attributes)
- **`vertical`** (Boolean): 开启垂直表单布局。
- **`inline`** (Boolean): 开启无边框的流式行内布局（常用于顶部工具栏）。
- **`nobutton`** (Boolean): 隐藏底部的默认提交/保存按钮。
- **`api`** (String / Element): 绑定页面中 `<API>` 组件的 ID（或直接为组件实例引用），以便在提交时自动对接。
- **`submitlabel`** (String): 自定义提交按钮的文本内容。默认为 `"{#Submit#}"`。
### 2. 实例编程接口
- **`data`** (读写): 表单内部数据的响应式 Proxy 模型（映射至 `state.data`）。可直接通过 `Object.assign(form.data, newData)` 或逐个属性赋值来修改表单中的值。
- **`request`** (读写): 默认提交配置，默认为 `{ method: 'POST' }`。
- **`response`** (只读): 提交请求返回的完整响应对象。
- **`result`** (只读): 提交请求返回的 `response.result`。
- **`submit(opt = {})`**
- **用途**：手动触发表单校验与提交。
- **校验逻辑**：通过原生 `form.reportValidity()` 校验。若失败，调用 `UI.toast` 提示 `"{#verify failed#}"` 并退出。
- **提交逻辑**：如果绑定了 `api` 属性，则调用 `api.do(req)`（其中 `req.data` 自动绑定为表单 `data`）；否则，如果配置了 `request.url`，则直接调用 `HTTP.request(req)`；两者皆无则在控制台抛出警告。
### 3. Schema 项目 (`FormItem`) 结构定义
`state.schema` 数组中每一项可配置的字段：
- **`name`** (String, 必填): 数据字段键名，与 `form.data` 中的属性双向绑定。
- **`label`** (String, 可选): 表单项标签名称（仅在非 `inline` 模式下展示）。
- **`type`** (String, 必填): 表单控件类型。
- 原生支持：`'text'`, `'password'`, `'email'`, `'number'`, `'date'`, `'datetime'`, `'file'`, `'select'`, `'checkbox'`, `'radio'`, `'switch'`, `'textarea'`。
- 扩展注册支持：如 `'DatePicker'`, `'ColorPicker'`, `'IconPicker'`, `'TagsInput'`。
- **`if`** (String, 可选): 控制是否显示该表单项的条件表达式字符串。使用双重计算渲染（`$$if`），其执行上下文中 `this` 指向 AutoForm 组件实例，可以通过 `this.data` 引用其他字段值。
- **`setting`** (Object, 可选): 原生属性透传对象，会通过 `$.="item.setting || {}"` 绑定到控件上。
- **`options`** (Array, 可选): 针对 `select`, `checkbox`, `radio` 类型。
- 格式可以为扁平字符串数组：`['Option1', 'Option2']`
- 也可以为键值对数组：`[{ label: '选项1', value: 'val1' }]`
- **`placeholder`** (String, 可选): 仅对 `select` 类型有效，表示未选中时的禁用占位选项。
- **`vertical`** (Boolean, 可选): 仅对 `checkbox` 或 `radio` 类型有效。若为 `true`，各选项纵向排列；默认为 `false`（横向排列）。
- **`text` / `label`** (String, 可选): 当 `checkbox` 或 `radio` 未提供 `options` 选项时，使用此值作为单选项的标签，其选中时的值是 `'on'`。
### 4. 插槽 (Slots)
- **`actions`**：在表单底部提交按钮左侧的区域插槽（仅在非 `inline` 且非 `nobutton` 模式下渲染）。
### 5. 事件派发
- **`submit`**：在开始提交数据前触发。
- `bubbles`: `false`
- `cancelable`: `true`（调用 `event.preventDefault()` 可彻底终止提交动作）
- `detail`: 当前表单的数据对象 `container.data`。
- **`response`**：表单自动提交成功并得到接口响应后触发。
- `bubbles`: `false`
- `cancelable`: `false`
- `detail`: 完整的响应对象 `resp`。
- **`error`**：提交失败（网络错、校验错或返回的 json 带有 error 字段）时触发。
- `bubbles`: `true`
- `cancelable`: `false`
- `detail`: Error 对象。
### 6. 表单控件扩展机制 (`AutoForm.register`)
- **`AutoForm.register(name, typeName)`**
- **用途**：将第三方/自定义 Web Component 注册为表单的自定义控件类型。
- **参数**：
- `name` (String): 组件标签名（如 `'DatePicker'`）。
- `typeName` (String, 可选): schema 中对应的 `type` 字符串。不传则默认等同于 `name`。
- **实现逻辑**：当在 AutoForm 的 `schema` 中匹配到对应 `type` 时，自动在 DOM 树中插入该自定义组件，并将其属性 `$.` 绑定为 `item.setting`，其值 `bind` 双向绑定到 AutoForm 的对应数据字段。
<!-- endsection: form -->
---
<!-- section: extension-controls -->
## 五、 表单自定义扩展组件
### 1. 日期选择器 (`<DatePicker>`)
- **核心能力**：支持单日期选择，或双日期范围选择（主字段 + 影子字段模式）。
- **启用范围选择**：在 AutoForm 的对应 Schema 项目中，配置 `setting.rangeEnd: "endFieldName"`；或在组件上直接配置 `rangeEnd` 属性。
- **内部状态 (`state`)**：
- `start` (String): 开始日期。
- `end` (String): 结束日期。
- **实例属性**：
- `value` (读写): 映射至 `state.start`。
- `isRange` (只读): 根据是否配置了 `rangeEnd` 返回 `Boolean` 值。
- **操作方法**：
- `updateStart(val)`: 更新 `state.start` 并分发 `change` 事件。
- `updateEnd(val)`: 更新 `state.end`，若处于 AutoForm 容器中，将该值同步写入到表单数据的 `rangeEnd` 对应字段中。
- **事件派发**：
- `'change'`：当主字段/开始日期发生改变时触发。
- `bubbles`: `true`
- `detail`: 改变后的开始日期字符串（`state.start`）。
### 2. 颜色选择器 (`<ColorPicker>`)
- **核心能力**：提供颜色取色器（`type="color"`）与十六进制文本输入框的双向联动。
- **内部状态 (`state`)**：
- `value` (String): 颜色值，默认为 `'#000000'`。
- **实例属性**：
- `value` (读写): 映射至 `state.value`。
- **方法**：
- `updateValue(val)`: 更新颜色状态并分发事件。
- **事件派发**：
- `'change'`：当值发生改变时触发。
- `bubbles`: `true`
- `detail`: 改变后的十六进制颜色字符串。
### 3. 图标选择器 (`<IconPicker>`)
- **核心能力**：基于 Bootstrap Icons 的可视化下拉搜索选择器。
- **内部状态 (`state`)**：
- `value` (String): 当前选中的图标名。
- `search` (String): 图标搜索关键字。
- `open` (Boolean): 下拉菜单的展开状态。
- **实例属性**：
- `value` (读写): 映射至 `state.value`。
- `filteredIcons` (只读): 经过 `search` 关键字过滤后的图标名称列表。
- **方法**：
- `selectIcon(icon)`: 选中指定图标，收起下拉框并派发 `change` 事件。
- `toggle()`: 切换下拉框展开状态。若展开，会自动延时聚焦在搜索输入框中。
- **事件派发**：
- `'change'`：当选中图标发生改变时触发。
- `bubbles`: `true`
- `detail`: 选中的图标类名。
- *点击外部收起*：监听全局 `click` 事件，点击外部自动收起下拉框；组件被移除 DOM 时自动注销该监听。
### 4. 标签输入框 (`<TagsInput>`)
- **核心能力**：可视化添加和删除标签。
- **添加交互**：在输入框中输入内容后，按 `Enter`, `,` (逗号) 或 ` ` (空格) 会自动将标签加入。
- **删除交互**：点击标签聚焦后，按 `Backspace` 或 `Delete` 键可将其移除，并自动聚焦到前一个标签。
- **内部状态 (`state`)**：
- `tags` (Array): 存储标签字符串的数组。
- **实例属性**：
- `value` (读写): 映射至 `state.tags`。
- **事件派发**：
- `'change'`：当标签数组发生增删改变时触发。
- `bubbles`: `true`
- `detail`: 最新标签的字符串数组。
<!-- endsection: extension-controls -->
---
<!-- section: list -->
## 六、 增强列表组件 (`<List>`)
### 1. 列表布局模式 (`mode` Attribute)
- **`normal`** (默认): 扁平列表模式。
- **`group`** (分组):
- 关联逻辑：通过 `list` 中成员的 `groupfield` 匹配 `groups` 数组中项的 `groupidfield`。
- **`tree`** (树形):
- 关联逻辑：扁平化数组，通过每一项的 `parentfield` 匹配父项的 `idfield`。根项的值为空字符串 `''`。
### 2. 字段映射配置属性 (可重写默认值)
在组件初始化时，会调用 `Util.updateDefaults` 将以下属性更新为默认值：
- `idfield`: 项的主键字段名，默认 `'id'`。
- `labelfield`: 项展示文本字段名，默认 `'label'`。
- `summaryfield`: 项辅助文本字段名，默认 `'summary'`。
- `groupidfield`: 分组的主键字段名，默认 `'id'`。
- `grouplabelfield`: 分组展示文本字段名，默认 `'label'`。
- `groupsummaryfield`: 分组辅助文本字段名，默认 `'summary'`。
- `groupfield`: 项关联分组的字段名，默认 `'group'`。
- `parentfield`: 树形下关联父节点的字段名，默认 `'parent'`。
- `groupicon`: 组/父节点的图标类，默认 `'folder'` (对应 Bootstrap Icons 的类名)。
- `itemicon`: 项/叶子节点的图标类，默认 `'file'`。
### 3. 功能属性 (Attributes)
- **`fast`** (Boolean): 启用虚拟滚动。
- **重要约束**：`<List>` 容器必须包含 Bootstrap 的 `overflow-auto` 类，且内置 `style="overflow-anchor:none"`（模板自带）。
- **`collapsible`** (Boolean): 仅在 `tree` 模式下有效，开启树形节点的展开/收起能力。
- **`auto-select`** (Boolean): 开启后，点击列表项时自动将该项的 `id` 记录至 `state.selectedItem`，如果重复点击则会置空。
- **`auto-select-group`** (Boolean): 开启后，点击分组时自动将分组的 `id` 记录至 `state.selectedGroup`。
### 4. 内部状态模型 (`State`)
- `list` (读写): 原始列表数据数组。
- `groups` (读写): 仅在 `group` 模式下使用，分组定义数组。
- `collapsed` (读写): 仅在 `tree` 且 `collapsible` 时使用，存储节点 ID 折叠状态的 Map Proxy。
- `selectedItem` (读写): 当前选中的列表项 ID。
- `selectedGroup` (读写): 当前选中的分组 ID。
- `_flatList` (只读): 列表核心逻辑处理后的扁平化数组。
- `_renderedList` (只读): 实际在 DOM 中遍历渲染的数组片段（若开启虚拟滚动，则只包含可视区切片）。
### 5. 插槽 (Slots)
- **`item`**：列表单项渲染模板插槽。在自定义模板中，可以访问当前行数据 `item` 和索引 `index`。
- **`item-actions`**：行数据右侧按钮工具栏区域。
- **`group-actions`**：分组数据行右侧按钮工具栏区域。
### 6. 虚拟滚动运行参数
- **高度优先规则**：
若列表数据的某一项上配置了数字属性 `_itemHeight`，虚拟滚动引擎会将其作为该项的测量高度，直接跳过 DOM 的高度测量。
### 7. 事件派发
- **`itemclick`**：点击列表项（非分组）时触发。
- `bubbles`: `false`
- `detail`: `{ item, index }` (其中 `index` 为考虑虚拟滚动偏移量后的 **绝对全局索引**)。
- **`groupclick`**：点击分组行时触发。
- `bubbles`: `false`
- `detail`: `{ item, index }`。
<!-- endsection: list -->
---
<!-- section: nav -->
## 七、 导航组件 (`<Nav>`)
### 1. 结构与属性
- **`vertical`** (Attribute, Boolean): 决定导航为垂直面板布局（带有右侧分割线）或水平导航栏布局（带底部阴影）。
### 2. 响应式数据模型 (`State`)
- **`brand`** (Object, 可选): `{ image, icon, label }`，控制左上角/顶部的 Logo、图标及品牌文本。
- **`list`** (Array, 必填): 导航栏项的数组。
### 3. 导航项结构（`list` 成员）
- **`type`**: 决定导航项的渲染模式：
- `'button'`: 导航按钮。
- `'dropdown'`: 下拉菜单导航。含有 `list` (子项数组)，子项类型可为：
- `'button'`: 子项按钮。
- `'switch'`: 状态开关。需要配置 `bind` (状态Proxy引用) 和 `name` (要绑定的字段名)。
- 水平布局下可以通过 `width` (Number) 控制下拉菜单宽度，默认 `250`。
- `'fill'`: 弹性填充块（`flex-fill`），用于实现右对齐等布局。
- **`name`** (String): 导航标识。当点击导航按钮时，该 `name` 会自动被写入 `Hash.nav` 以同步 URL 哈希。
- **`label`** (String): 文本展示。
- **`icon`** (String): 图标类名（基于 Bootstrap Icons）。
- **`noselect`** (Boolean, 可选): 若为 `true`，点击该项仅派发点击事件，**不会** 修改 `Hash.nav`。
### 4. 事件派发
- **`nav`**：点击任何菜单项或下拉子菜单项时触发。
- `bubbles`: `false`
- `detail`: `{ item }` (被点击的导航项数据定义)。
<!-- endsection: nav -->
---
<!-- section: resizer -->
## 八、 拖拽改变大小组件 (`<Resizer>`)
### 1. 组件属性
- **`vertical`** (Attribute, Boolean): 为 `true` 时，鼠标为 `row-resize`，调整高度；默认调整宽度。
- **`min`** (Attribute, Number): 像素下限，默认 `10`。
- **`max`** (Attribute, Number): 像素上限，默认 `1000`。
- **`target`** (Element): 要调整大小的目标 DOM 元素。默认是组件的前一个兄弟节点 (`container.previousElementSibling`)。
### 2. 事件与双向绑定
- **`bind`** (输入拦截): 支持通过绑定表达式传入像素值（数字），自动设置为 target 的 `width`/`height`。
- **`resizing`**：拖动调整大小的过程中持续触发。
- `bubbles`: `false`
- `detail`: `{ oldSize, newSize }`
- **`resize`**：拖动结束时触发。
- `bubbles`: `false`
- `detail`: `{ oldSize, newSize }`
- **`change`**：拖动结束时触发，输出最终的大小数值。常用于将新尺寸写回全局 `State`。
- `bubbles`: `false`
- `detail`: `newSize` (Number)
<!-- endsection: resizer -->
---
<!-- section: ui -->
## 九、 编程交互工具集 (`UI`)
### 1. 核心对话框方法 (`UI.showDialog`)
- **`UI.showDialog({ title, message, buttons, type })`**
- **参数**：
- `title` (String, 可选): 对话框标题。
- `message` (String, 必填): 提示消息，支持 HTML 标记（`$html` 渲染）。
- `buttons` (Array, 可选): 按钮文字数组，默认 `['{#Close#}']`。
- `type` (String, 可选): 主题类型 `'primary' | 'danger' | 'warning' | 'success'` 等，控制边框、标题及最后一个主按钮的颜色。
- **返回值**：`Promise<Number>`。
- 点击按钮返回其索引值 (从 `1` 开始)。
- 点击关闭图标或按 ESC 取消返回 `0`。
### 2. 快捷对话框
- **`UI.alert(message, options)`**：包装 `UI.showDialog`。
- **`UI.confirm(message, options)`**：确认框。
- 默认按钮：`['{#Cancel#}', '{#Confirm#}']`。
- 返回值：`Promise<Boolean>` (选中确认按钮为 `true`，取消为 `false`)。
### 3. 轻提示方法 (`UI.toast`)
- **`UI.toast(message, options)`**
- **参数**：
- `message` (String, 必填): 消息文本。
- `options` (Object, 可选)：
- `delay` (Number): 自动关闭延迟时间（毫秒），默认 `5000`。若传入 `0` 则永久不消失。
- `type` (String): 主题背景色 `'primary' | 'success' | 'danger' | 'warning'` 等。
- `buttons` (Array): 自定义 Toast 内嵌按钮，点击会设置 `result = index + 1` 并在点击后自动 dismiss。
- `container` (String): 目标 Toast 容器 ID，默认 `'default'`。
### 4. 快捷 Toast 确认
- **`UI.toastConfirm(message, options)`**
- 弹出带有一个 `Confirm` 按钮的 Toast。
- 返回值：`Promise<Boolean>`（点击确认按钮返回 `true`，其余情况返回 `false`）。
<!-- endsection: ui -->

19
CHANGELOG.md
View File

@ -1,5 +1,24 @@
# Changelog # Changelog
## [1.0.10] - 2026-06-05
### Fixed
- List: Removed reactive data-binding for `prevHeight` and `postHeight` and refactored virtual scroll to directly mutate padding DOM node heights, preventing reactive re-render overhead.
- List: Ignored elements with `offsetHeight === 0` during layout measurement, preventing hidden tab state (display: none) from polluting height average `avg`.
- List: Applied a safety minimum limit (16px) to average item height calculations to prevent `visibleCount` explosion.
- List: Implemented a synchronization re-entry lock using `setTimeout` in list refresh to cut recursive `scroll` event loops.
- Config: Configured `server.fs.allow: ['..']` in vite.config.js to allow local development cross-directory assets access (like fonts).
- Dependency: Updated `@apigo.cc/state` CDN script dependency to `1.0.15`.
## [1.0.9] - 2026-06-05
### Changed
- Document: Comprehensive rewrite of base/README.md utilizing example-driven and static declaration binding paradigm.
- Document: Created base/CAPABILITY.md as the 100% complete spec checklist for all components and API.
- Config: Updated @apigo.cc/state dependency reference to v1.0.13.
## [1.0.8] - 2026-06-05
### Changed
- Bump version and align dependencies.
## [1.0.7] - 2026-05-29 ## [1.0.7] - 2026-05-29
### Added ### Added
- DatePicker: New control with range support (main/shadow field sync). - DatePicker: New control with range support (main/shadow field sync).

344
README.md
View File

@ -1,112 +1,288 @@
# @apigo.cc/base AI 开发指南 (全面版) # @apigo.cc/base - AI 逻辑操作说明书 (示例驱动)
`@apigo.cc/base` 是基于 State.js 构建的高性能 Web 基础组件库。它采用**原生 ESM、零打包**架构，深度集成 Bootstrap 5，旨在为 AI 驱动的开发提供极致精简且功能完备的 UI 与逻辑基建。 本库是基于 `@apigo.cc/state` 增强的 UI 原子库，提供遵循 Bootstrap 5.3 规范的高阶业务组件。
--- ---
## 一、 快速开始 ## 1. 快速集成 (Quick Start)
### 1. 引入依赖
在 HTML 中配置 `importmap`。推荐使用 `loader.js` 自动管理：
### CDN 集成 (自包含 UMD，锁定版本号，无需引入 Bootstrap CSS)
```html ```html
<!-- 依赖 Bootstrap 5 --> <!-- 依赖核心库 -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet"> <script src="https://cdn.jsdelivr.net/npm/@apigo.cc/state@1.0.15/dist/state.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script> <!-- Bootstrap 集成引擎 (自包含 CSS 注入) -->
<script src="https://cdn.jsdelivr.net/npm/@apigo.cc/bootstrap@1.0.5/dist/bootstrap.min.js"></script>
<!-- 本组件库 -->
<script src="https://cdn.jsdelivr.net/npm/@apigo.cc/base@1.0.10/dist/base.min.js"></script>
```
<script type="importmap"> ### ESM 模块引入
{ ```javascript
"imports": { import { HTTP, UI, AutoForm, State } from '@apigo.cc/base'
"@apigo.cc/state": "path/to/state.mjs", ```
"@apigo.cc/base": "path/to/base.mjs"
---
## 2. 组件超能力示例 (Mega Examples)
### 2.1 声明式数据组件 (`<API>`)
```html
<API id="userSearchApi" auto
$request='{
"url": "/api/users/search",
"method": "POST",
"data": { "keyword": State.searchKey }
}'
$onresponse="console.log('加载成功，响应对象:', event.detail); State.userList = event.detail.result"
$onerror="UI.toast('加载失败：' + event.detail.message, { type: 'danger' })">
</API>
<script>
// 手动调用 API 示例 (适合动态触发/事后赋值场景)
async function forceReload() {
try {
// do() 返回 Promise<ResponseObject>。传入 noui: true 屏蔽全局 UI 弹窗报错。
const resp = await userSearchApi.do({ noui: true });
console.log("手动加载完成，结果:", resp.result);
} catch (err) {
console.error("请求失败", err);
}
} }
}
</script> </script>
``` ```
* **AI 核心要点**：
### 2. 导出清单 * **请求响应结构 (ResponseObject)**：
* **Logic**: `HTTP`, `UI`, `State`, `MouseMover` `{ ok: Boolean, status: Number, headers: Object, responseType: 'json'|'binary'|'text', result: Any, error: String|null }`
* **Components**: `<API>`, `<Modal>`, `<Dialog>`, `<Toast>`, `<AutoForm>`, `<TagsInput>`, `<DatePicker>`, `<ColorPicker>`, `<IconPicker>`, `<FastList>`, `<List>`, `<GroupedList>`, `<FastGroupedList>`, `<Tree>`, `<FastTree>`, `<CollapseTree>`, `<Nav>`, `<Resizer>` * 深度监听 `request` 任何字段的改变自动触发请求（微任务防抖）。`response` 事件为 `bubbles: false`，`error` 为 `bubbles: true`。
--- ---
## 二、 核心组件详述 ### 2.2 万能表单与内嵌控件 (`<AutoForm>`)
### 1. 网络与数据 (`HTTP` & `<API>`)
* **`HTTP`**: 静态请求工具（`get`, `post`, `put`, `delete`, `request`）。
* **`<API>`**: 声明式请求容器。
* `$.request.url`: 请求地址。
* `auto`: 属性存在时，url 变化自动触发请求。
* `@response`: 请求成功事件。
### 2. UI 交互 (Namespace `UI`)
* `UI.alert(msg)` / `UI.confirm(msg)`: 基础对话框。
* `UI.toast(msg, {type: 'success'})`: 自动消失的轻提示。
### 3. 数据驱动表单 (`<AutoForm>`)
核心配置项：`$.state.schema` (结构) 和 `data` (响应式数据)。
* **`data`**: 表单实时绑定的响应式对象 (建议通过 `NewState` 创建)。
* **`field.if`**: 支持使用字符串表达式进行联动显隐。在表达式中可通过 `this.data` 访问表单数据。
**示例 (动态联动显隐):**
```html ```html
<AutoForm <script>
$.state.schema="[ // 1. 预先确定表单 Schema (合并了所有扩展控件配置)
{name:'type', type:'select', options:['personal', 'company'], label:'类型'}, const employeeFormSchema = [
{name:'taxId', type:'text', label:'税号', if: 'this.data.type === \'company\''} { name: 'name', label: '姓名', type: 'text', setting: { required: true } },
]" {
$.data="formState"> name: 'joinDate',
label: '入职周期',
type: 'DatePicker', // 内置日期范围选择控件
setting: { rangeEnd: 'leaveDate' } // 影子字段绑定为 leaveDate
},
{ name: 'color', label: '工位颜色', type: 'ColorPicker' }, // 内置颜色控件
{ name: 'avatarIcon', label: '头像图标', type: 'IconPicker' }, // 内置图标控件
{ name: 'skills', label: '专业技能', type: 'TagsInput' }, // 内置多标签控件
{
name: 'role',
label: '角色',
type: 'select',
options: [{ label: '管理员', value: 'admin' }, { label: '员工', value: 'staff' }],
placeholder: '请选择角色...'
},
{
name: 'status',
label: '状态',
type: 'checkbox',
options: ['在职', '离职'],
if: "this.data.age > 18" // 仅在 age > 18 时渲染，this 访问 AutoForm 实例
},
{ name: 'notify', label: '启用通知', type: 'switch' }
];
</script>
<!-- 2. HTML 声明式属性绑定 schema 状态，且绑定接口 API 实例 -->
<AutoForm id="employeeForm"
vertical
$state.schema="employeeFormSchema"
$api="saveEmployeeApi"
$onresponse="UI.toast('保存成功！')">
</AutoForm> </AutoForm>
<script>
// 3. 数据层回显/事后赋值操作 (使用 Object.assign 保证绑定的 Proxy 响应式链路不丢失)
Object.assign(employeeForm.state.data, {
name: '张三',
joinDate: '2026-06-01',
leaveDate: '2026-06-30',
color: '#ff0000',
avatarIcon: 'person',
skills: ['Vue', 'React'],
role: 'staff',
notify: true
});
</script>
``` ```
* **AI 核心要点**：
* 容器属性：`vertical` (垂直排列)、`inline` (无边框流式行内布局)、`nobutton` (隐藏底部默认按钮)。
* **表单数据操作红线**：禁止对 `form.state.data` 或 `form.data` 执行覆盖式重新赋值，必须使用 `Object.assign`。
#### 新增高级表单控件 ---
* **`<DatePicker>`**: 支持范围选择。设置 `setting: { rangeEnd: 'field_name' }` 即可开启范围模式，自动同步结束日期到指定字段。
* **`<ColorPicker>`**: 颜色选择器，支持可视化选取及十六进制文本同步。
* **`<IconPicker>`**: 基于 Bootstrap Icons 的可视化图标选择器，支持搜索过滤。
### 4. 高性能列表 (`<FastList>` 家族) ### 2.3 增强列表组件 (`<List>`)
支持万级数据、动态高度、虚拟滚动。
| 组件名 | 特点 | 列表有三类布局模式，分别有不同的数据结构关联，均推荐在 HTML 中声明绑定：
| :--- | :--- |
| `<FastList>` | 基础虚拟滚动列表。 |
| `<FastGroupedList>` | 带分组的虚拟列表。 |
| `<FastTree>` | 虚拟滚动树。 |
| `<CollapseTree>` | 支持折叠的树结构。 |
**示例 (动态高度列表):** #### 模式一：普通扁平列表 (`mode="normal"`)
* **关联逻辑**：直接渲染一维数组项。
* **数据结构**：
```javascript
const userList = [
{ id: '1', label: '小明', summary: '前端开发' },
{ id: '2', label: '小红', summary: '产品经理' }
];
```
* **HTML 写法**：
```html
<List mode="normal" $list="userList" $onitemclick="console.log(event.detail.item)"></List>
```
#### 模式二：分组列表 (`mode="group"`)
* **关联逻辑**：`list` 的项通过 `group` 字段去匹配 `groups` 数组中的 `id` 字段。
* **数据结构**：
```javascript
const deptGroups = [
{ id: 'devGroup', label: '研发中心', summary: '共 5 人' },
{ id: 'hrGroup', label: '人力资源', summary: '共 2 人' }
];
const groupUserList = [
{ id: '1', label: '小明', group: 'devGroup' },
{ id: '2', label: '小红', group: 'hrGroup' }
];
```
* **HTML 写法**：
```html
<List mode="group" $list="groupUserList" $state.groups="deptGroups"></List>
```
#### 模式三：树形可折叠列表 (`mode="tree"`) —— 超级示例
* **关联逻辑**：通过每项的 `parent` 关联父项的 `id` 属性，根项的 `parent` 设为空字符串 `''`。
* **数据结构**（内置 `_itemHeight` 优化虚拟滚动高度测量）：
```javascript
const deptTreeList = [
{ id: '1', label: '总经办', parent: '', _itemHeight: 40 },
{ id: '2', label: '研发部', parent: '1', _itemHeight: 40 },
{ id: '3', label: '开发组', parent: '2', _itemHeight: 40 }
];
```
* **HTML 写法**：
```html
<List id="orgTreeList"
mode="tree"
fast
collapsible
auto-select
class="overflow-auto border"
style="height: 400px;"
$list="deptTreeList"
$onitemclick="console.log('点击节点:', event.detail.item, '全局绝对索引:', event.detail.index)">
<!-- 自定义单项右侧动作区域 -->
<template slot-id="item">
<span class="fw-semibold text-primary" $text="item.label"></span>
<div slot-id="item-actions">
<button class="btn btn-sm btn-link py-0 bi bi-plus-circle" onclick="addNode(item)"></button>
</div>
</template>
</List>
```
* **AI 核心要点**：
* **属性默认值**：当数据结构符合默认字段命名（`id`, `label`, `summary`, `parent`, `group`）时，**无须填写**任何映射属性（如 `idfield`, `labelfield`, `parentfield` 等），实际编写代码时应当将其省略。
* 虚拟滚动 (`fast`) 强制容器必须声明为 `overflow-auto` 类。
---
### 2.4 导航组件 (`<Nav>`)
```html ```html
<FastList $.state.list="items"> <script>
<div slot="item" $.style.height="${item.h}px" $text="item.label"></div> // 1. 预先确定品牌与菜单数据
</FastList> const myBrand = { icon: 'shield-lock', label: '安全控制台' };
const myNavList = [
{ type: 'button', name: 'dashboard', label: '仪表盘', icon: 'speedometer' },
{
type: 'dropdown',
name: 'settings',
label: '系统设置',
icon: 'gear',
list: [
{ type: 'button', name: 'profile', label: '个人信息', icon: 'person' },
{ type: 'switch', name: 'darkMode', label: '暗黑模式', icon: 'moon', bind: LocalStorage, name: 'darkMode' }
]
},
{ type: 'fill' },
{ type: 'button', name: 'logout', label: '退出登录', icon: 'box-arrow-right', noselect: true }
];
</script>
<!-- 2. HTML 声明式属性绑定 -->
<Nav id="sidebarNav"
vertical
$state.brand="myBrand"
$state.list="myNavList"
$onnav="console.log('导航点击:', event.detail.item)">
</Nav>
``` ```
* **AI 核心要点**：
* 常规导航项被点击时（且 `noselect` 不为 true），会自动更新全局 `Hash.nav = item.name`。
--- ---
## 三、 组件详细清单与 API ### 2.5 拖拽改变大小组件 (`<Resizer>`)
```html
### 逻辑类 (JS API) <div class="d-flex" style="height: 300px;">
* **`HTTP.request(opt)`**: 返回 `Promise`，结果包含 `ok`, `status`, `result`, `error`。 <div id="leftPanel" style="width: 200px;" class="bg-light">侧边栏</div>
* **`UI.showDialog({title, message, buttons, type})`**: 弹出自定义对话框。 <!-- 拖拽调节器，默认 target 为前一个兄弟节点 -->
* **`MouseMover.start(event, callbacks)`**: 全局鼠标移动监听（用于拖拽）。 <Resizer target="leftPanel"
min="100"
### 组件类 (Custom Elements) max="400"
* **`<Modal>`**: $onresizing="console.log('拖动尺寸:', event.detail.newSize)"
* `$bind="state.show"`: 双向绑定显隐。 $change="State.leftPanelWidth">
* `slot-id="header/body/footer"`: 内容插槽。 </Resizer>
* **`<TagsInput>`**: 标签录入，绑定数据为字符串数组。 <div class="flex-fill">内容区</div>
* **`<Nav>`**: 响应式导航栏。 </div>
* `$.state.brand`: `{image, icon, label}`。 ```
* `$.state.list`: 菜单数组。 * **AI 核心要点**：
* **`<Resizer>`**: * `resizing` 与 `resize` 事件的 `detail` 结构均为 `{ oldSize: Number, newSize: Number }`；`change` 事件的 `detail` 为 `newSize` 像素数字。
* `vertical`: 属性，切换水平/垂直。
* `min/max`: 限制尺寸。
--- ---
## 四、 最佳实践 (AI 指令) ## 3. 网络与交互工具集 (`HTTP` & `UI`)
1. **拒绝手动 DOM 操作**: 优先使用 `$bind` 和 `$.state` 驱动 UI。
2. **列表性能**: 大数据量（>50条）强制使用 `Fast` 系列组件。 ### 3.1 HTTP 请求工具 (`HTTP`)
3. **样式优先**: 优先使用 Bootstrap 5 Utility classes (如 `d-flex`, `p-3`, `gap-2`)。 ```javascript
4. **微任务**: 涉及 DOM 尺寸计算的代码必须包裹在 `Promise.resolve().then(() => { ... })` 中。 // 支持 HTTP.get, HTTP.post, HTTP.put, HTTP.delete, HTTP.head
const resp = await HTTP.post({
url: '/api/user/save',
data: { name: 'Alice', file: avatarFile },
timeout: 5000
});
```
* **返回值 `ResponseObject` 结构**：
* `ok` (Boolean): 状态码是否在 200-299。
* `status` (Number): HTTP 状态码。
* `headers` (Object): 响应头键值对。
* `responseType` (String): `'json' | 'binary' | 'text'`。
* `result` (Any): 成功后的解析结果。
* `error` (String | null): 失败的错误描述。
* **数据自动转换**：若 `data` 内包含 `File`/`Blob`，自动转为 `FormData` 且清除 Content-Type；普通对象自动序列化为 JSON 并添加 `application/json`。
### 3.2 交互工具 (`UI`)
* **`UI.showDialog({ title, message, buttons, type })`**
* **返回值**：`Promise<Number>`。点击按钮返回其索引值 (从 `1` 开始)，点击关闭或取消返回 `0`。
* **参数**：`type` 可以为 `'primary'|'danger'|'warning'|'success'` 控制主题色；`message` 支持 HTML。
* **`UI.alert(message, options)`**
* **返回值**：`Promise<Boolean>`（点击关闭按钮返回 `false`）。
* **`UI.confirm(message, options)`**
* **返回值**：`Promise<Boolean>`。点击“确认”返回 `true`，点击“取消”或关闭返回 `false`。
* **`UI.toast(message, options)`**
* **返回值**：`void`。`options.delay` 为自动消失延迟毫秒（`0` 代表不消失）。可以通过传入 `buttons: ['选项1']` 按钮提供交互，点击后在实例 `result` 上保存索引。
* **`UI.toastConfirm(message, options)`**
* **返回值**：`Promise<Boolean>`。在 Toast 中提供单确认按钮，点击确认返回 `true`，否则返回 `false`。
---
## 4. 开发红线 (Constraints)
1. **表单数据操作红线**：严禁直接覆盖表单的 `state.data` 或 `data` 对象（如 `form.data = {}`）。这会切断与内部 Proxy 的响应式链路。必须使用 `Object.assign(form.state.data, newData)`。
2. **列表布局红线**：开启虚拟滚动（`fast`）时，容器必须包含 `overflow-auto` 类。
3. **指令 DOM 保护**：严禁使用原生 DOM API 直接修改由 `$each`、`$if` 或组件渲染指令生成的 DOM 节点。所有 DOM 状态的变化应当完全通过修改与之绑定的底层 `State` 属性驱动。
4. **退出拦截约束**：在全局配置有 `State.exitBlocks > 0` 时，框架将强行拦截并警告任何刷新/关闭页面的行为。

1391
dist/base.js vendored
View File

File diff suppressed because one or more lines are too long

2
dist/base.min.js vendored
View File

File diff suppressed because one or more lines are too long

1
dist/base.min.mjs vendored Normal file
View File

File diff suppressed because one or more lines are too long

920
dist/base.mjs vendored Normal file
View File

File diff suppressed because one or more lines are too long

17
node_modules/.vite/deps/_metadata.json generated vendored
View File

@ -1,8 +1,15 @@
{ {
"hash": "5a59143b", "hash": "945ec9e8",
"configHash": "a1c4c8e0", "configHash": "6c629749",
"lockfileHash": "6014e7a8", "lockfileHash": "463a0a64",
"browserHash": "c3b48a46", "browserHash": "38e755dd",
"optimized": {}, "optimized": {
"bootstrap": {
"src": "../../../../bootstrap/node_modules/bootstrap/dist/js/bootstrap.esm.js",
"file": "bootstrap.js",
"fileHash": "b9d6a4a2",
"needsInterop": false
}
},
"chunks": {} "chunks": {}
} }

5188
node_modules/.vite/deps/bootstrap.js generated vendored Normal file
View File

File diff suppressed because it is too large Load Diff

7
node_modules/.vite/deps/bootstrap.js.map generated vendored Normal file
View File

File diff suppressed because one or more lines are too long

2
package.json
View File

@ -1,6 +1,6 @@
{ {
"name": "@apigo.cc/base", "name": "@apigo.cc/base",
"version": "1.0.8", "version": "1.0.10",
"type": "module", "type": "module",
"main": "dist/base.js", "main": "dist/base.js",
"module": "dist/base.js", "module": "dist/base.js",

15
src/index.js
View File

@ -1,4 +1,5 @@
import { NewState } from '@apigo.cc/state' import { NewState, State } from '@apigo.cc/state'
import '@apigo.cc/bootstrap'
// Re-exports // Re-exports
export * from './http.js' export * from './http.js'
@ -9,9 +10,7 @@ export * from './list.js'
export * from './nav.js' export * from './nav.js'
export * from './interaction.js' export * from './interaction.js'
// 页面退出状态 export { State }
export const State = NewState({ exitBlocks: 0 })
globalThis.State = State
if (typeof window !== 'undefined') { if (typeof window !== 'undefined') {
window.addEventListener('beforeunload', (event) => { window.addEventListener('beforeunload', (event) => {
@ -29,14 +28,22 @@ import { HTTP } from './http.js'
import { UI } from './ui.js' import { UI } from './ui.js'
import { AutoForm } from './form.js' import { AutoForm } from './form.js'
import { MouseMover } from './interaction.js' import { MouseMover } from './interaction.js'
import { VirtualScroll } from './list.js'
globalThis.HTTP = HTTP globalThis.HTTP = HTTP
globalThis.UI = UI globalThis.UI = UI
globalThis.AutoForm = AutoForm globalThis.AutoForm = AutoForm
globalThis.MouseMover = MouseMover globalThis.MouseMover = MouseMover
globalThis.VirtualScroll = VirtualScroll
const ApigoBase = {
HTTP, UI, AutoForm, MouseMover, VirtualScroll, State
};
import { RefreshState } from '@apigo.cc/state' import { RefreshState } from '@apigo.cc/state'
if (typeof document !== 'undefined') { if (typeof document !== 'undefined') {
globalThis.ApigoBase = ApigoBase;
const doRefresh = () => RefreshState(document.documentElement) const doRefresh = () => RefreshState(document.documentElement)
if (document.readyState !== 'loading') setTimeout(doRefresh, 1) if (document.readyState !== 'loading') setTimeout(doRefresh, 1)
else document.addEventListener('DOMContentLoaded', () => setTimeout(doRefresh, 1), true) else document.addEventListener('DOMContentLoaded', () => setTimeout(doRefresh, 1), true)

44
src/list.js
View File

@ -47,6 +47,7 @@ export const VirtualScroll = (options = {}) => {
listInited = true; refreshCallback(); listInited = true; refreshCallback();
}, },
update: (absoluteIndex, node) => { update: (absoluteIndex, node) => {
if (node.offsetHeight === 0) return;
if (itemMarginTop === null) { if (itemMarginTop === null) {
const style = window.getComputedStyle(node); const style = window.getComputedStyle(node);
itemMarginTop = parseFloat(style.marginTop) || 0; itemMarginBottom = parseFloat(style.marginBottom) || 0; itemMarginTop = parseFloat(style.marginTop) || 0; itemMarginBottom = parseFloat(style.marginBottom) || 0;
@ -63,12 +64,17 @@ export const VirtualScroll = (options = {}) => {
calc: (container, list) => { calc: (container, list) => {
if (!listInited || !list) return null; if (!listInited || !list) return null;
const size = list.length; const size = list.length;
let visibleCount = Math.max(10, Math.ceil((container.clientHeight || 100) / (avg.get() || 32))); const avgVal = Math.max(16, avg.get() || 32);
let visibleCount = Math.max(10, Math.ceil((container.clientHeight || 100) / avgVal));
let prev = padTop + topMargin + rowGap, post = 0, status = 0, listStartIndex = 0, listEndIndex = 0; let prev = padTop + topMargin + rowGap, post = 0, status = 0, listStartIndex = 0, listEndIndex = 0;
let renderedList = []; let renderedList = [];
const scrollTop = container.scrollTop; const scrollTop = container.scrollTop;
let loopCount = 0;
for (let i = 0; i < size; i++) { for (let i = 0; i < size; i++) {
if (++loopCount > size * 2) {
throw new Error(`VirtualScroll.calc infinite loop detected at i=${i}, status=${status}, size=${size}, groupItemCount=${groupItemCount}`);
}
if (status === 0) { if (status === 0) {
const gh = groupHeights.get(i); const gh = groupHeights.get(i);
if (gh && prev + gh <= scrollTop && (i + groupItemCount < size)) { if (gh && prev + gh <= scrollTop && (i + groupItemCount < size)) {
@ -114,6 +120,9 @@ Component.register('List', container => {
container.fast = container.hasAttribute('fast') container.fast = container.hasAttribute('fast')
container.collapsible = container.hasAttribute('collapsible') container.collapsible = container.hasAttribute('collapsible')
const padTopEl = container.fast ? container.querySelector('.vs-pad-top') : null
const padBottomEl = container.fast ? container.querySelector('.vs-pad-bottom') : null
const defaultSets = { const defaultSets = {
idfield: 'id', labelfield: 'label', summaryfield: 'summary', idfield: 'id', labelfield: 'label', summaryfield: 'summary',
groupidfield: 'id', grouplabelfield: 'label', groupsummaryfield: 'summary', groupfield: 'group', groupidfield: 'id', grouplabelfield: 'label', groupsummaryfield: 'summary', groupfield: 'group',
@ -150,14 +159,27 @@ Component.register('List', container => {
const vs = container.fast ? VirtualScroll() : null const vs = container.fast ? VirtualScroll() : null
container.state._renderedList = [] container.state._renderedList = []
let refreshing = false
container.refresh = () => { container.refresh = () => {
if (!container.fast) return if (!container.fast || refreshing) return
const res = vs.calc(container, container.state._flatList) refreshing = true
if (res) { try {
container.state.prevHeight = res.prevHeight const res = vs.calc(container, container.state._flatList)
container.state.postHeight = res.postHeight if (res) {
container.state._listStartIndex = res.listStartIndex if (padTopEl) padTopEl.style.height = `${res.prevHeight}px`
container.state._renderedList = res.renderedList if (padBottomEl) padBottomEl.style.height = `${res.postHeight}px`
if (container.state._listStartIndex !== res.listStartIndex) {
container.state._listStartIndex = res.listStartIndex
}
const cur = container.state._renderedList || []
if (cur.length !== res.renderedList.length || cur[0] !== res.renderedList[0] || cur[cur.length - 1] !== res.renderedList[res.renderedList.length - 1]) {
container.state._renderedList = res.renderedList
}
}
} finally {
setTimeout(() => { refreshing = false }, 0)
} }
} }
@ -165,6 +187,8 @@ Component.register('List', container => {
container.state.__watch('_flatList', flatList => { container.state.__watch('_flatList', flatList => {
if (container.fast) { if (container.fast) {
if (padTopEl) padTopEl.style.height = '0px'
if (padBottomEl) padBottomEl.style.height = '0px'
container.state._listStartIndex = 0 container.state._listStartIndex = 0
container.state._renderedList = vs.reset(flatList, container) || [] container.state._renderedList = vs.reset(flatList, container) || []
setTimeout(() => { if (container.state._flatList === flatList) vs.init(flatList, container.refresh) }) setTimeout(() => { if (container.state._flatList === flatList) vs.init(flatList, container.refresh) })
@ -184,7 +208,7 @@ Component.register('List', container => {
updateFlatList() updateFlatList()
}, Util.makeDom(/*html*/` }, Util.makeDom(/*html*/`
<div class="list-group overflow-auto" onscroll="this.refresh()" style="overflow-anchor:none"> <div class="list-group overflow-auto" onscroll="this.refresh()" style="overflow-anchor:none">
<div $if="this.fast && (this.state?.prevHeight || 0) > 0" $style="height:\${this.state?.prevHeight}px;" class="flex-shrink-0"></div> <div class="vs-pad-top flex-shrink-0" style="height:0px;"></div>
<template slot-id="item" $each="this.state?._renderedList"> <template slot-id="item" $each="this.state?._renderedList">
<div $onupdate="this.onItemUpdate(index, thisNode)" $class="list-group-item list-group-item-action d-inline-flex align-items-center ps-2 pe-2 \${item.type==='group'?(this.state?.selectedGroup===item[this.groupidfield]?'active':''):(this.state?.selectedItem===item[this.idfield]?'active':'')}" $onclick="item.type==='group'?this.selectGroup(item,index):this.selectItem(item,index)"> <div $onupdate="this.onItemUpdate(index, thisNode)" $class="list-group-item list-group-item-action d-inline-flex align-items-center ps-2 pe-2 \${item.type==='group'?(this.state?.selectedGroup===item[this.groupidfield]?'active':''):(this.state?.selectedItem===item[this.idfield]?'active':'')}" $onclick="item.type==='group'?this.selectGroup(item,index):this.selectItem(item,index)">
<template $if="item.type === 'group'"> <template $if="item.type === 'group'">
@ -205,6 +229,6 @@ Component.register('List', container => {
</template> </template>
</div> </div>
</template> </template>
<div $if="this.fast && (this.state?.postHeight || 0) > 0" $style="height:\${this.state?.postHeight}px;" class="flex-shrink-0"></div> <div class="vs-pad-bottom flex-shrink-0" style="height:0px;"></div>
</div> </div>
`)) `))

6
test-results/.last-run.json
View File

@ -1,6 +1,4 @@
{ {
"status": "failed", "status": "passed",
"failedTests": [ "failedTests": []
"8a84b43f13b676ea22b7-4f4df3778b9a6eb1af05"
]
} }

24
test-results/all-base-project-comprehen-6c76e-ts-and-scrolling-benchmarks/error-context.md
View File

@ -1,24 +0,0 @@
# Instructions
- Following Playwright test failed.
- Explain why, be concise, respect Playwright best practices.
- Provide a snippet of code with the fix, if possible.
# Test info
- Name: all.spec.js >> base project comprehensive tests and scrolling benchmarks
- Location: test/all.spec.js:3:1
# Error details
```
Error: page.evaluate: TypeError: Cannot read properties of null (reading 'scrollTop')
at eval (eval at evaluate (:302:30), <anonymous>:9:21)
at async <anonymous>:328:30
```
# Page snapshot
```yaml
- heading "All Tests Passed 🎉" [level=1] [ref=e3]
```

1
test/all.spec.js
View File

@ -3,6 +3,7 @@ import { test, expect } from '@playwright/test';
test('base project comprehensive tests and scrolling benchmarks', async ({ page }) => { test('base project comprehensive tests and scrolling benchmarks', async ({ page }) => {
test.setTimeout(60000); test.setTimeout(60000);
page.on('console', msg => console.log('BROWSER LOG:', msg.text())); page.on('console', msg => console.log('BROWSER LOG:', msg.text()));
page.on('pageerror', err => console.log('BROWSER EXCEPTION:', err.message, err.stack));
await page.goto('http://127.0.0.1:8082/test/index.html'); await page.goto('http://127.0.0.1:8082/test/index.html');
// Wait for testStatus to be set (includes basic unit tests and scrolling refresh test) // Wait for testStatus to be set (includes basic unit tests and scrolling refresh test)

4
test/base.test.js
View File

@ -111,9 +111,13 @@ export async function runTests() {
await new Promise(r => setTimeout(r, 100)); // wait for render await new Promise(r => setTimeout(r, 100)); // wait for render
const el = document.getElementById(id); const el = document.getElementById(id);
const start = performance.now(); const start = performance.now();
console.log(`[MEASURE] ${name} setting scrollTop to 5000`);
el.scrollTop = 5000; el.scrollTop = 5000;
console.log(`[MEASURE] ${name} calling refresh`);
el.refresh?.(); el.refresh?.();
console.log(`[MEASURE] ${name} refresh called, waiting 50ms`);
await new Promise(r => setTimeout(r, 50)); await new Promise(r => setTimeout(r, 50));
console.log(`[MEASURE] ${name} wait done`);
const time = performance.now() - start; const time = performance.now() - start;
window.benchResults[name] = time; window.benchResults[name] = time;
console.log(`BENCHMARK: ${name} scroll & refresh: ${time.toFixed(2)}ms`); console.log(`BENCHMARK: ${name} scroll & refresh: ${time.toFixed(2)}ms`);

4
test/index.html
View File

@ -15,6 +15,10 @@
</script> </script>
</head> </head>
<body class="d-flex flex-column vh-100"> <body class="d-flex flex-column vh-100">
<script>
window.addEventListener('error', e => console.log('GLOBAL ERROR:', e.message, e.filename, e.lineno, e.colno, e.error));
window.addEventListener('unhandledrejection', e => console.log('UNHANDLED REJECTION:', e.reason));
</script>
<div id="results" class="p-2 bg-light border-bottom">Running tests...</div> <div id="results" class="p-2 bg-light border-bottom">Running tests...</div>
<script> <script>

31
vite.config.js
View File

@ -6,6 +6,7 @@ export default defineConfig({
resolve: { resolve: {
alias: { alias: {
'@apigo.cc/state': resolve(__dirname, '../state/src/index.js'), '@apigo.cc/state': resolve(__dirname, '../state/src/index.js'),
'@apigo.cc/bootstrap': resolve(__dirname, '../bootstrap/src/index.js'),
'@apigo.cc/base': resolve(__dirname, 'src/index.js') '@apigo.cc/base': resolve(__dirname, 'src/index.js')
} }
}, },
@ -17,20 +18,38 @@ export default defineConfig({
build: { build: {
lib: { lib: {
entry: resolve(__dirname, 'src/index.js'), entry: resolve(__dirname, 'src/index.js'),
name: 'Base', name: 'ApigoBase',
formats: ['es'] formats: ['umd', 'es']
}, },
rollupOptions: { rollupOptions: {
external: ['@apigo.cc/state'], external: ['@apigo.cc/state', '@apigo.cc/bootstrap'],
output: [ output: [
{ {
format: 'es', format: 'umd',
name: 'ApigoBase',
entryFileNames: 'base.js', entryFileNames: 'base.js',
minifyInternalExports: false globals: {
'@apigo.cc/state': 'ApigoState',
'@apigo.cc/bootstrap': 'bootstrap'
}
},
{
format: 'umd',
name: 'ApigoBase',
entryFileNames: 'base.min.js',
globals: {
'@apigo.cc/state': 'ApigoState',
'@apigo.cc/bootstrap': 'bootstrap'
},
plugins: [terser()]
}, },
{ {
format: 'es', format: 'es',
entryFileNames: 'base.min.js', entryFileNames: 'base.mjs'
},
{
format: 'es',
entryFileNames: 'base.min.mjs',
plugins: [terser()] plugins: [terser()]
} }
] ]