npm package: @k3000/ce
Description: 这是一个极轻量、**零构建 (No Build)** 的原生 Web Components 框架。它利用现代浏览器的 ES Modules 和 Custom Elements API，无需任何打包工具。
Latest version: 0.4.0

# @k3000/ce - Custom Element 响应式框架

这是一个极轻量、**零构建 (No Build)** 的原生 Web Components 框架。它利用现代浏览器的 ES Modules 和 Custom Elements API，无需任何打包工具。

链接：[讨论沟通链接](https://qshfu.com/doc/index.html#/public/MKjPmZhaz)
---

## ✨ 核心特性

- 🚀 **零构建**: 无需 Webpack/Vite，直接在浏览器运行。
- ⚛️ **响应式系统**: 基于 `Object.defineProperty` 的自动数据追踪与视图更新。
- 模板指令**: 内置 `each` (循环)、`connect` (条件渲染) 指令。
- 🛠️ **响应式 Hooks**: 提供 `useAttr`, `useWatch`, `useRef`, `useEvent` 等现代 API。

---

## 🚀 快速上手

### 1. 全局安装
```
.\> npm i @k3000/ce
.\> cd demo #进入需要的目录
.\demo>npx ce copy #复制核心框架文件可以带参数，ce copy dist.js，将ce.mjs复制到当前目录，并改名为：dist.js
.\demo>npx ce demo #复制使用示例一共三个目录和一个数据文件：/app、/comm、/console、/info.json
```

### 2. 项目引入
在 `index.html` 中通过 Script 标签引入核心框架：

```html
<script type="module">
    import { config } from '../ce.mjs'

    config({
        dir: './console/components',
        ext: 'mjs'
    })
</script>
```

### 3. 定义组件
每个组件为一个独立的 `.mjs` 文件。

**示例: `my-counter.mjs`**

```javascript
import { useWatch } from "../../ce.mjs";

// 1. 定义 HTML 结构 (支持插值 {{ }})
export const innerHTML = `
<div class="p-4 border rounded-xl shadow-lg bg-white/60 backdrop-blur-md">
    <h3 class="text-lg font-bold">计数器: {{count}}</h3>
    <div class="mt-4 gap-2 flex">
        <button onclick="{{increment}}" class="px-4 py-2 bg-blue-500 text-white rounded-lg">+1</button>
        <button onclick="{{() => this.count = 0}}" class="px-4 py-2 bg-gray-200 rounded-lg">重置</button>
    </div>
</div>
`;

// 2. 定义逻辑
export default class extends HTMLElement {
    count = 0;

    constructor() {
        super();
        this.style.display = 'contents';
        
        // 开启响应式监听 (可选，模板中使用的变量会自动监听)
        const watch = useWatch(this);
        watch({
            count: (val) => console.log('Count changed to:', val)
        });
    }

    increment() {
        this.count++;
    }
}
```

---

## 📖 核心 API (Hooks)

### `useAttr(this)`
获取当前组件的所有 HTML 属性，返回一个简单的键值对对象。
```javascript
const attr = useAttr(this);
console.log(attr.title); // 获取 <my-comp title="xxx"></my-comp> 的值
```

### `useRef(this)`
获取模板中标记了 `ref` 属性的 DOM 元素。
```javascript
// HTML: <path ref="pathNode"></path>
ready() {
    const refs = useRef(this);
    refs.pathNode.setAttribute('d', 'M10 10...');
}
```

### `useWatch(target)`
手动对对象属性进行响应式监听。
```javascript
const watch = useWatch(this.data);
watch({
    username: (newVal, oldVal) => {
        // 返回 false 可以阻止赋值
        return true;
    }
}, true); // 第二个参数为 true 表示立即执行一次
```

### `useEvent()`
获取全局事件总线，用于跨组件通信。
```javascript
const event = useEvent();
event.dispatch('user-login', { id: 1 }); // 发送事件
event.add('user-login', (data) => { ... }); // 监听事件
```

---

## 🏗️ 模板指令
`getVariables`读取模板字符串内变量集合
`createTmpNode`创建一个临时的 node 占位
`literalsCode`处理输出的字符串
`functionCode`处理输出的代码块
`handleArray`处理实现<element each="{{[1,2,3]}}"></element>的循环
`valueChanged`特殊处理 INPUT、TEXTAREA、SELECT value={{val}} 的时候会处理相应自定义逻辑

### `each="{{list}}"` (循环)
```html
<tr each="{{userList}}" class="hover:bg-gray-50">
    <td>{{username}}</td>
    <td>{{email}}</td>
</tr>
```

### `connect="{{isVisible}}"` (条件渲染)
类似于 `v-if`，控制元素在 DOM 树中的物理存在。
```html
<div connect="{{status === 'active'}}">
    现在可见
</div>
```

### `on[event]="{{handler}}"` (事件绑定)
```html
<button onclick="{{handleClick}}">方法绑定</button>
<button onclick="{{() => this.count++}}">内联绑定</button>
```

### `value="{{val}}"` INPUT、TEXTAREA、SELECT 绑定的 value 会通过 valueChanged 去处理，默认是处理 value 变化反向更新数据
```html
<input value="{{val}}" />
// 默认 input onchange 事件会更新 val 的值。
```

---
## ✍ 可自定义handle

---
## ⚠️ 注意事项
- **ES Modules**: 必须在 HTTP 服务器环境下运行。
- **作用域**: 模板指令中的代码默认运行在组件实例的作用域下。
- **ready()**: 当你需要操作 DOM 时，请在 `ready()` 生命周期中执行。