# @web/base AI 开发指南 (全面版)

`@web/base` 是基于 State.js 构建的高性能 Web 基础组件库。它采用**原生 ESM、零打包**架构，深度集成 Bootstrap 5，旨在为 AI 驱动的开发提供极致精简且功能完备的 UI 与逻辑基建。

---

## 一、 快速开始

### 1. 引入依赖
在 HTML 中配置 `importmap`。推荐使用 `loader.js` 自动管理：

```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/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>

<script type="importmap">
{
  "imports": {
    "@web/state": "path/to/state.mjs",
    "@web/base": "path/to/base.mjs"
  }
}
</script>
```

### 2. 导出清单
*   **Logic**: `HTTP`, `UI`, `State`, `MouseMover`
*   **Components**: `<API>`, `<Modal>`, `<Dialog>`, `<Toast>`, `<AutoForm>`, `<TagsInput>`, `<FastList>`, `<List>`, `<GroupedList>`, `<FastGroupedList>`, `<Tree>`, `<FastTree>`, `<CollapseTree>`, `<Nav>`, `<Resizer>`

---

## 二、 核心组件详述

### 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` (结构) 和 `$.state.data` (数据)。

```html
<AutoForm 
  $.state.schema="[
    {name:'user', type:'text', label:'用户名', required:true},
    {name:'role', type:'select', options:['Admin', 'User'], label:'角色'}
  ]"
  $.state.data="myData">
</AutoForm>
```

### 4. 高性能列表 (`<FastList>` 家族)
支持万级数据、动态高度、虚拟滚动。

| 组件名 | 特点 |
| :--- | :--- |
| `<FastList>` | 基础虚拟滚动列表。 |
| `<FastGroupedList>` | 带分组的虚拟列表。 |
| `<FastTree>` | 虚拟滚动树。 |
| `<CollapseTree>` | 支持折叠的树结构。 |

**示例 (动态高度列表):**
```html
<FastList $.state.list="items">
  <div slot="item" $.style.height="${item.h}px" $text="item.label"></div>
</FastList>
```

---

## 三、 组件详细清单与 API

### 逻辑类 (JS API)
*   **`HTTP.request(opt)`**: 返回 `Promise`，结果包含 `ok`, `status`, `result`, `error`。
*   **`UI.showDialog({title, message, buttons, type})`**: 弹出自定义对话框。
*   **`MouseMover.start(event, callbacks)`**: 全局鼠标移动监听（用于拖拽）。

### 组件类 (Custom Elements)
*   **`<Modal>`**: 
    *   `$bind="state.show"`: 双向绑定显隐。
    *   `slot-id="header/body/footer"`: 内容插槽。
*   **`<TagsInput>`**: 标签录入，绑定数据为字符串数组。
*   **`<Nav>`**: 响应式导航栏。
    *   `$.state.brand`: `{image, icon, label}`。
    *   `$.state.list`: 菜单数组。
*   **`<Resizer>`**: 
    *   `vertical`: 属性，切换水平/垂直。
    *   `min/max`: 限制尺寸。

---

## 四、 最佳实践 (AI 指令)
1.  **拒绝手动 DOM 操作**: 优先使用 `$bind` 和 `$.state` 驱动 UI。
2.  **列表性能**: 大数据量（>50条）强制使用 `Fast` 系列组件。
3.  **样式优先**: 优先使用 Bootstrap 5 Utility classes (如 `d-flex`, `p-3`, `gap-2`)。
4.  **微任务**: 涉及 DOM 尺寸计算的代码必须包裹在 `Promise.resolve().then(() => { ... })` 中。