@lytjs/core 5.0.0 → 6.0.0

package/README.md

@@ -1,288 +1,328 @@
-# @lytjs/core
-
-Lyt.js 核心入口 - 整合响应式、编译器、虚拟 DOM、渲染器和组件系统，提供完整的应用开发能力。
-
-## 安装
-
-```bash
-npm install @lytjs/core
-
-# 或使用 pnpm
-pnpm add @lytjs/core
-```
-
-## 特性
-
-- 🚀 零运行时依赖，极致轻量
-- 🎨 所见即代码，无 `v-` 前缀的模板语法
-- 🔄 完整的 Composition API
-- 📦 内置组件系统、插槽、KeepAlive、Suspense
-- 🌐 Web Component 支持
-- 🔌 插件系统
-
-## 快速开始
-
-### 创建应用
-
-```javascript
-import { createApp, defineComponent, h } from '@lytjs/core';
-
-const App = defineComponent({
-  setup() {
-    return { count: 0 };
-  },
-  render() {
-    return h('div', [
-      h('h1', `Count: ${this.count}`),
-      h('button', {
-        onClick: () => this.count++
-      }, 'Increment')
-    ]);
-  }
-});
-
-const app = createApp(App);
-app.mount('#app');
-```
-
-### 使用模板
-
-```javascript
-import { createApp, defineComponent } from '@lytjs/core';
-
-const App = defineComponent({
-  setup() {
-    return { count: 0 };
-  },
-  template: `
-    <div>
-      <h1>Count: {{ count }}</h1>
-      <button @click="count++">Increment</button>
-    </div>
-  `
-});
-
-const app = createApp(App);
-app.mount('#app');
-```
-
-### 使用插件
-
-```javascript
-import { createApp, defineComponent } from '@lytjs/core';
-
-const myPlugin = {
-  install(app, options) {
-    app.config.globalProperties.$hello = 'Hello from plugin!';
-  }
-};
-
-const app = createApp(App);
-app.use(myPlugin, { someOption: true });
-app.mount('#app');
-```
-
-### Web Component
-
-```javascript
-import { defineCustomElement, defineComponent } from '@lytjs/core';
-
-const MyComponent = defineComponent({
-  props: ['name'],
-  template: `<div>Hello, {{ name }}!</div>`
-});
-
-customElements.define('my-component', defineCustomElement(MyComponent));
-```
-
-## API 参考
-
-### 应用 API
-
-| API | 说明 |
-|------|------|
-| `createApp(rootComponent, rootProps)` | 创建应用实例 |
-| `createSSRApp(rootComponent, rootProps)` | 创建 SSR 应用实例 |
-
-### 应用实例
-
-| API | 说明 |
-|------|------|
-| `app.mount(container)` | 挂载应用到 DOM 容器 |
-| `app.unmount()` | 卸载应用 |
-| `app.use(plugin, options)` | 安装插件 |
-| `app.component(name, component)` | 注册全局组件 |
-| `app.directive(name, directive)` | 注册全局指令 |
-| `app.provide(key, value)` | 全局提供值 |
-| `app.config` | 应用配置对象 |
-
-### 组件定义
-
-| API | 说明 |
-|------|------|
-| `defineComponent(options)` | 定义组件 |
-| `defineAsyncComponent(loader)` | 定义异步组件 |
-| `resolveComponent(name)` | 解析组件 |
-
-### 渲染 API
-
-| API | 说明 |
-|------|------|
-| `h(type, props, children)` | 创建虚拟节点 |
-| `render(vnode, container)` | 渲染虚拟节点 |
-
-### 依赖注入
-
-| API | 说明 |
-|------|------|
-| `provide(key, value)` | 提供值给后代组件 |
-| `inject(key, defaultValue)` | 注入祖先组件提供的值 |
-
-### 内置组件
-
-| 组件 | 说明 |
-|------|------|
-| `KeepAlive` | 缓存失活组件实例 |
-| `Teleport` | 将内容渲染到指定 DOM 位置 |
-| `Transition` | 单个元素/组件的过渡动画 |
-| `TransitionGroup` | 列表的过渡动画 |
-| `Suspense` | 等待异步依赖 |
-
-## 模板语法
-
-Lyt.js 的模板语法与原生 HTML 更接近，去掉了 `v-` 前缀：
-
-### 插值
-
-```html
-<span>Text: {{ message }}</span>
-```
-
-### 指令
-
-```html
-<!-- 条件渲染 -->
-<div if="visible">显示</div>
-<div else-if="pending">加载中...</div>
-<div else>隐藏</div>
-
-<!-- 列表渲染 -->
-<ul>
-  <li each="(item, index) in items" :key="item.id">
-    {{ index }}: {{ item.text }}
-  </li>
-</ul>
-
-<!-- 事件绑定 -->
-<button @click="handleClick">点击</button>
-<input @input="handleInput" />
-
-<!-- 属性绑定 -->
-<img :src="imageUrl" :alt="altText" />
-<div :class="{ active: isActive }"></div>
-```
-
-## 组件生命周期
-
-```javascript
-import { defineComponent, onMounted, onUpdated, onUnmounted } from '@lytjs/core';
-
-const MyComponent = defineComponent({
-  setup() {
-    onMounted(() => {
-      console.log('组件已挂载');
-    });
-
-    onUpdated(() => {
-      console.log('组件已更新');
-    });
-
-    onUnmounted(() => {
-      console.log('组件已卸载');
-    });
-
-    return {};
-  }
-});
-```
-
-| 生命周期 | 说明 |
-|----------|------|
-| `onBeforeMount` | 组件挂载前 |
-| `onMounted` | 组件挂载后 |
-| `onBeforeUpdate` | 组件更新前 |
-| `onUpdated` | 组件更新后 |
-| `onBeforeUnmount` | 组件卸载前 |
-| `onUnmounted` | 组件卸载后 |
-
-## 示例
-
-### Todo List
-
-```javascript
-import { createApp, defineComponent, ref } from '@lytjs/core';
-
-const App = defineComponent({
-  setup() {
-    const todos = ref([{ id: 1, text: 'Learn Lyt.js', done: false }]);
-    const newTodo = ref('');
-
-    function addTodo() {
-      if (newTodo.value.trim()) {
-        todos.value.push({
-          id: Date.now(),
-          text: newTodo.value,
-          done: false
-        });
-        newTodo.value = '';
-      }
-    }
-
-    function toggleTodo(todo) {
-      todo.done = !todo.done;
-    }
-
-    return { todos, newTodo, addTodo, toggleTodo };
-  },
-  template: `
-    <div>
-      <h1>Todo List</h1>
-      <div>
-        <input v-model="newTodo" @keyup.enter="addTodo" />
-        <button @click="addTodo">Add</button>
-      </div>
-      <ul>
-        <li 
-          each="todo in todos" 
-          :key="todo.id"
-          :class="{ done: todo.done }"
-          @click="toggleTodo(todo)"
-        >
-          {{ todo.text }}
-        </li>
-      </ul>
-    </div>
-  `
-});
-
-createApp(App).mount('#app');
-```
-
-## 性能
-
-- 核心体积：2.13 KB (ESM gzip)
-- 零运行时依赖
-- Block Tree 虚拟 DOM 优化
-- Patch Flag 差异化更新
-
-## 兼容性
-
-- Node.js >= 18.0.0
-- Chrome 64+
-- Firefox 63+
-- Safari 12+
-- Edge 79+
-
-## License
-
-MIT
+# @lytjs/core
+
+> LytJS 框架核心入口，整合响应式、编译器、虚拟 DOM、渲染器和组件系统
+
+## 安装
+
+```bash
+npm install @lytjs/core
+```
+
+## 核心 API
+
+### createApp
+
+创建应用实例，挂载根组件
+
+```typescript
+import { createApp, defineComponent } from '@lytjs/core';
+
+const RootComponent = defineComponent({
+  setup() {
+    const count = ref(0);
+    return () => h('div', count.value);
+  },
+});
+
+const app = createApp(RootComponent);
+app.mount('#app');
+```
+
+### h / createElement
+
+创建虚拟节点（JSX 工厂函数）
+
+```typescript
+import { h } from '@lytjs/core';
+
+// 创建元素
+const div = h('div', { class: 'container' }, 'Hello');
+
+// 创建组件
+const component = h(MyComponent, { prop: 'value' });
+
+// 嵌套子节点
+const nested = h('div', null, [h('span', null, 'Child 1'), h('span', null, 'Child 2')]);
+```
+
+### defineComponent / defineAsyncComponent
+
+定义组件和异步组件
+
+```typescript
+import { defineComponent, defineAsyncComponent } from '@lytjs/core';
+
+// 同步组件
+const MyComponent = defineComponent({
+  name: 'MyComponent',
+  props: {
+    title: String,
+  },
+  setup(props) {
+    return () => h('div', props.title);
+  },
+});
+
+// 异步组件
+const AsyncComponent = defineAsyncComponent(() => import('./HeavyComponent.vue'));
+```
+
+### nextTick
+
+在下一个 DOM 更新周期后执行回调
+
+```typescript
+import { nextTick, ref } from '@lytjs/core';
+
+const count = ref(0);
+count.value++;
+
+// 等待 DOM 更新
+await nextTick();
+// 或使用回调
+nextTick(() => {
+  console.log('DOM updated');
+});
+```
+
+## 响应式 API
+
+从 @lytjs/reactivity 重导出
+
+```typescript
+import {
+  ref,
+  reactive,
+  shallowRef,
+  shallowReactive,
+  readonly,
+  shallowReadonly,
+  computed,
+  watch,
+  watchEffect,
+  watchPostEffect,
+  watchSyncEffect,
+  effect,
+  stop,
+  toRef,
+  toRefs,
+  unref,
+  toValue,
+  customRef,
+  isRef,
+  isReactive,
+  isReadonly,
+  isProxy,
+  toRaw,
+  markRaw,
+  triggerRef,
+  provide,
+  inject,
+  // Signal API
+  signal,
+  computed as signalComputed,
+  writableComputedSignal,
+  readonlySignal,
+  set,
+  update,
+  valueOf,
+  signalBatch,
+  signalUntrack,
+  // 类型守卫
+  isShallowRef,
+  isComputedRef,
+} from '@lytjs/core';
+```
+
+## 生命周期钩子
+
+```typescript
+import {
+  onMounted,
+  onUnmounted,
+  onUpdated,
+  onBeforeMount,
+  onBeforeUpdate,
+  onBeforeUnmount,
+  onErrorCaptured,
+  onActivated,
+  onDeactivated,
+  onRenderTracked,
+  onRenderTriggered,
+} from '@lytjs/core';
+```
+
+## 编译 API
+
+从 @lytjs/compiler 重导出
+
+```typescript
+import { compile, parse, transform, generate } from '@lytjs/core';
+
+const { code, ast } = compile('<div>{{ message }}</div>');
+```
+
+## 内置组件
+
+```typescript
+import {
+  KeepAlive,
+  Suspense,
+  Transition,
+  TransitionGroup,
+  Teleport,
+  ErrorBoundary,
+} from '@lytjs/core';
+```
+
+### KeepAlive
+
+缓存非活动组件实例
+
+```typescript
+import { KeepAlive, ref } from '@lytjs/core';
+
+const current = ref('ComponentA');
+
+<KeepAlive include="ComponentA,ComponentB" :max="10">
+  <component :is="current" />
+</KeepAlive>
+```
+
+### Suspense
+
+处理异步组件加载
+
+```typescript
+import { Suspense, defineAsyncComponent } from '@lytjs/core';
+
+const AsyncComponent = defineAsyncComponent(() => import('./Heavy.vue'));
+
+<Suspense>
+  <template #default>
+    <AsyncComponent />
+  </template>
+  <template #fallback>
+    <div>Loading...</div>
+  </template>
+</Suspense>
+```
+
+### Transition / TransitionGroup
+
+过渡动画
+
+```typescript
+import { Transition, TransitionGroup } from '@lytjs/core';
+
+<Transition name="fade" mode="out-in">
+  <div :key="id">Content</div>
+</Transition>
+
+<TransitionGroup name="list" tag="ul">
+  <li v-for="item in items" :key="item.id">{{ item.name }}</li>
+</TransitionGroup>
+```
+
+### Teleport
+
+传送内容到指定位置
+
+```typescript
+import { Teleport } from '@lytjs/core';
+
+<Teleport to="body">
+  <div class="modal">Modal content</div>
+</Teleport>
+```
+
+### ErrorBoundary
+
+错误边界，捕获子组件错误
+
+```typescript
+import { ErrorBoundary } from '@lytjs/core';
+
+<ErrorBoundary :on-error="handleError" :capture-promise-rejections="true">
+  <MyComponent />
+  <template #fallback="{ error }">
+    <div>Error: {{ error?.message }}</div>
+  </template>
+</ErrorBoundary>
+```
+
+## 渲染 API
+
+```typescript
+import {
+  createRenderer,
+  createDOMRenderer,
+  renderToString,
+  renderToStream,
+  createSignalRenderer,
+  createVaporRenderer,
+  createVaporApp,
+  defineVaporComponent,
+} from '@lytjs/core';
+```
+
+## 工具函数
+
+```typescript
+import {
+  mergeProps,
+  cloneVNode,
+  normalizeClass,
+  normalizeStyle,
+  normalizeProps,
+} from '@lytjs/core';
+```
+
+## 类型定义
+
+```typescript
+import type {
+  // 组件类型
+  ComponentOptions,
+  ComponentPublicInstance,
+  ComponentInternalInstance,
+  SetupContext,
+  PropOptions,
+  // VNode 类型
+  VNode,
+  VNodeTypes,
+  VNodeChildren,
+  // 响应式类型
+  Ref,
+  ShallowRef,
+  ComputedRef,
+  ReactiveEffectRunner,
+  WatchOptions,
+  WatchCallback,
+  WatchHandle,
+  // 编译类型
+  CompilerOptions,
+  CodegenResult,
+  // 渲染类型
+  RendererOptions,
+  RendererPlugin,
+} from '@lytjs/core';
+```
+
+## 子包
+
+@lytjs/core 整合以下子包：
+
+| 包名                               | 说明             |
+| ---------------------------------- | ---------------- |
+| [@lytjs/reactivity](../reactivity) | 响应式系统       |
+| [@lytjs/vdom](../vdom)             | 虚拟 DOM 实现    |
+| [@lytjs/compiler](../compiler)     | 模板编译器       |
+| [@lytjs/renderer](../renderer)     | DOM/SSR 渲染后端 |
+| [@lytjs/component](../component)   | 组件系统         |
+| [@lytjs/common](../common)         | 公共工具库       |
+
+## 相关包
+
+- [@lytjs/adapter-web](../adapter-web) - Web 平台适配器
+- [@lytjs/host-contract](../host-contract) - 渲染器宿主抽象