@kupola/kupola 1.9.16 → 2.0.0-beta.1

package/README.md

@@ -1,487 +1,335 @@
-# Kupola
-
-> A lightweight, dependency-free declarative UI component system for server-side rendered web applications.
->
-> 零外部框架依赖的声明式 UI 组件系统，适用于任何服务端渲染 Web 应用。
-
-[![License](https://img.shields.io/github/license/kupola-cn/kupola)](https://github.com/kupola-cn/kupola/blob/main/LICENSE)
-[![npm](https://img.shields.io/npm/v/@kupola/kupola)](https://www.npmjs.com/package/@kupola/kupola)
-[![bundle size (gzip)](https://img.shields.io/badge/gzip-75%20KB-blue)](https://bundlephobia.com/package/@kupola/kupola)
-[![GitHub stars](https://img.shields.io/github/stars/kupola-cn/kupola)](https://github.com/kupola-cn/kupola/stargazers)
-
-**HTMX** (data fetching) + **Alpine.js** (declarative interaction) + **Bootstrap** (component richness) — in one zero-dependency package.
-
----
-
-## 🌐 Languages / 语言
-
-- [English](#english)
-- [中文](#中文)
-
----
-
-## 📦 构建工具插件
-
-### Vite 插件
-
-```js
-// vite.config.js
-import { kupola } from '@kupola/kupola/vite';
-
-export default {
-  plugins: [kupola()]
-};
-```
-
-**配置选项：**
-
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `autoCSS` | boolean | `true` | 自动注入 Kupola CSS |
-| `autoImport` | boolean | `true` | 自动导入 `useDeps`/`useQuery` |
-| `devTools` | boolean | `true` | 开发模式下启用调试工具 |
-| `cssPath` | string | `null` | 自定义 CSS 路径 |
-| `themePreload` | boolean | `false` | 自动注入主题预加载脚本 |
+[中文文档](./README.zh-CN.md)
 
-### Webpack 插件
+![npm](https://img.shields.io/npm/v/@kupola/kupola)
+![bundlephobia](https://img.shields.io/bundlephobia/minzip/@kupola/kupola)
+![Build Status](https://img.shields.io/github/actions/workflow/status/kupola-cn/kupola/ci.yml)
+![License](https://img.shields.io/github/license/kupola-cn/kupola)
 
-```js
-// webpack.config.js
-const KupolaWebpackPlugin = require('@kupola/kupola/webpack');
-
-module.exports = {
-  plugins: [new KupolaWebpackPlugin()]
-};
-```
-
-**配置选项：**
-
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `autoCSS` | boolean | `true` | 自动注入 Kupola CSS |
-| `themePreload` | boolean | `false` | 自动注入主题预加载脚本 |
-| `cssPath` | string | `null` | 自定义 CSS 路径 |
-
-### themePreload 配置说明
-
-**默认值：`false`**（v1.9.13 变更）
-
-`themePreload` 用于在 CSS 加载前设置主题属性，防止主题切换时的闪屏问题。请根据你的使用方式决定是否开启：
-
-| 使用方式 | themePreload | 说明 |
-|---------|-------------|------|
-| **ESM + initTheme()** | `false`（默认） | JS 模块加载时自动初始化，无需预加载 |
-| **UMD / 纯 CSS** | `true` | 需要在 CSS 加载前设置主题，防止闪屏 |
-
-**开启示例：**
-
-```js
-// Vite
-kupola({ themePreload: true })
+# Kupola
 
-// Webpack
-new KupolaWebpackPlugin({ themePreload: true })
-```
+**A zero-framework-dependency declarative UI engine + component library for any server-rendered web application.**
 
 ---
 
-## 📖 Documentation
+## Features
 
-- [**用户文档**](https://kupola-cn.github.io/kupola/docs/index.html) — 安装、组件速查、核心 API、主题、后端集成
-- [**架构文档**](https://kupola-cn.github.io/kupola/docs/architecture.html) — 内部引擎、模块依赖、构建管线、贡献指南
+- ⚛️ **Signal-based Reactivity**: Fine-grained tracking via `signal` / `computed` / `effect` with automatic batched updates
+- 📝 **Template Literals**: `html` tagged template + `render` for instant DOM binding — no compilation step
+- 🖥️ **SSR Ready**: `renderToString` + `hydrate` for pristine hydration with zero client-side flicker
+- 🧩 **48+ Components, Tree-shakeable**: Modal, Table, Dropdown, Form… each component is independently bundled
+- 🪶 **Ultra-lightweight**: Core engine < 5KB gzip, zero third-party dependencies
 
 ---
 
-<a id="english"></a>
-## 📦 Build Tool Plugins
-
-### Vite Plugin
-
-```js
-// vite.config.js
-import { kupola } from '@kupola/kupola/vite';
-
-export default {
-  plugins: [kupola()]
-};
-```
-
-**Options:**
-
-| Option | Type | Default | Description |
-|--------|------|--------|-------------|
-| `autoCSS` | boolean | `true` | Auto inject Kupola CSS |
-| `autoImport` | boolean | `true` | Auto import `useDeps`/`useQuery` |
-| `devTools` | boolean | `true` | Enable dev tools in dev mode |
-| `cssPath` | string | `null` | Custom CSS path |
-| `themePreload` | boolean | `false` | Auto inject theme preload script |
-
-### Webpack Plugin
-
-```js
-// webpack.config.js
-const KupolaWebpackPlugin = require('@kupola/kupola/webpack');
+## Quick Start
 
-module.exports = {
-  plugins: [new KupolaWebpackPlugin()]
-};
+```html
+<script src="https://cdn.jsdelivr.net/npm/@kupola/kupola/dist/kupola-core.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@kupola/kupola/dist/kupola-core-directives.umd.js"></script>
+<div k-data="{ count: 0 }">
+  <button k-on:click="count++">Clicked {{ count }} times</button>
+</div>
+<script>
+  Kupola.walk(document.body);
+</script>
 ```
 
-**Options:**
-
-| Option | Type | Default | Description |
-|--------|------|--------|-------------|
-| `autoCSS` | boolean | `true` | Auto inject Kupola CSS |
-| `themePreload` | boolean | `false` | Auto inject theme preload script |
-| `cssPath` | string | `null` | Custom CSS path |
+Or use the programmatic API:
 
-### themePreload Configuration
-
-**Default: `false`** (Changed in v1.9.13)
-
-`themePreload` sets theme attributes before CSS loads to prevent flash of unstyled content during theme switching. Enable it based on your usage pattern:
-
-| Usage Pattern | themePreload | Reason |
-|--------------|-------------|--------|
-| **ESM + initTheme()** | `false` (default) | JS module initializes automatically on load |
-| **UMD / CSS-only** | `true` | Needs theme set before CSS loads to prevent flash |
-
-**Example with themePreload enabled:**
-
-```js
-// Vite
-kupola({ themePreload: true })
-
-// Webpack
-new KupolaWebpackPlugin({ themePreload: true })
+```html
+<div id="app"></div>
+<script type="module">
+  import { signal, html, render } from 'https://cdn.jsdelivr.net/npm/@kupola/kupola/dist/kupola-core.esm.js';
+
+  const count = signal(0);
+  const view = () => html`<button @click=${() => count.value++}>Clicked ${count} times</button>`;
+  render(view(), document.getElementById('app'));
+</script>
 ```
 
 ---
 
-## ✨ Features
-
-- **50+ UI Components** — Buttons, inputs, cards, modals, datepickers, timepickers, heatmap, virtual list, stat cards, and more
-- **Declarative Data Dependencies** — `useDeps()` with auto-caching, retry, refresh, and transform
-- **HTTP Client Plugin System** — Plug in Axios, @navios/http, or any HTTP client; interceptors preserved
-- **Reactive Data Binding** — Two-way binding with `ref()` / `store()` (Proxy-based)
-- **Dual Themes** — Dark-first design with light theme support
-- **11 Brand Colors** — Switchable brand themes inspired by Chinese traditional colors
-- **Responsive** — PC, Pad, and Phone
-- **Accessible** — WCAG AA compliant
-- **Form Validation** — Built-in validation with custom rules
-- **Zero Dependencies** — Pure HTML/CSS/JavaScript, ~75 KB minified gzipped
-- **Backend Agnostic** — Works with Flask, Django, FastAPI, Gin, Spring Boot, ASP.NET, Express, Rails, Actix-web, and any backend that outputs HTML
-- **TypeScript Ready** — Full type definitions included
-
----
+## Installation
 
-## 🚀 Quick Start
-
-### Scaffold (recommended)
-
-Create a fully configured Kupola project in seconds:
+> **Current version**: `2.0.0-alpha.1` (pre-release). Use `@next` tag to install:
 
 ```bash
-npx @kupola/create-kupola
+npm install @kupola/kupola@next              # Full package
+# Or core engine only
+npm install @kupola/kupola/core@next          # signal + template + render + SSR
 ```
 
-Choose from **Static**, **Flask**, **FastAPI**, or **Gin** — with dark theme, brand colors, and example pages out of the box.
-
-### npm
-
 ```bash
-npm install @kupola/kupola
-```
-
-```html
-<link rel="stylesheet" href="node_modules/@kupola/kupola/dist/css/kupola.css">
-<script src="node_modules/@kupola/kupola/dist/kupola.esm.js" type="module"></script>
-```
-
-### CDN
-
-```html
-<!-- ESM (modern browsers) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kupola/kupola/dist/css/kupola.css">
-<script src="https://cdn.jsdelivr.net/npm/@kupola/kupola/dist/kupola.esm.js" type="module"></script>
-
-<!-- UMD (legacy) -->
-<script src="https://cdn.jsdelivr.net/npm/@kupola/kupola/dist/kupola.umd.js"></script>
+# CDN
+https://cdn.jsdelivr.net/npm/@kupola/kupola@next/dist/kupola-core.esm.js
+https://cdn.jsdelivr.net/npm/@kupola/kupola@next/dist/kupola-core.cjs.js
 ```
 
 ---
 
-## 📦 Usage
+## Import Components on Demand
 
-### Components (HTML-only, no JS needed)
+Each component is independently bundled — import only what you need:
 
-```html
-<button class="ds-btn ds-btn--brand">Primary</button>
-<button class="ds-btn ds-btn--outline">Outline</button>
+```javascript
+// Import Modal only
+import { Modal } from '@kupola/kupola/components/modal';
 
-<div class="ds-card">
-  <div class="ds-card__header">
-    <h3 class="ds-card__title">Card Title</h3>
-  </div>
-  <div class="ds-card__body">Card content</div>
-</div>
+const modal = Modal({ title: 'Confirm', content: 'This action cannot be undone.' });
+modal.open();
 ```
 
-### Data Binding
-
-```html
-<input type="text" data-bind="user.name:value" placeholder="Name">
-<span data-bind="user.name:text"></span>
-```
-
-```js
-kupolaData.data.user = { name: 'John' };
-kupolaData.data.user.name = 'Jane';  // Auto-updates all bound elements
-```
-
-### Declarative Data Dependencies
-
-```html
-<div data-deps="users:fetch:/api/users">
-  <template data-each="users">
-    <span data-bind="item.name:text"></span>
-  </template>
-</div>
-```
-
-```js
-import { useDeps } from 'kupola';
-useDeps({ users: { url: '/api/users', staleTime: 60000 } });
-```
-
-### HTTP Client Plugin (Axios Example)
-
-```js
-import { configureHttpClient } from 'kupola';
-import { createAxiosAdapter } from 'kupola/adapters/axios';
-import axios from 'axios';
-
-const api = axios.create({ baseURL: '/api' });
-api.interceptors.request.use(config => {
-  config.headers.Authorization = `Bearer ${getToken()}`;
-  return config;
+```javascript
+// Import Table only
+import { Table } from '@kupola/kupola/components/table';
+
+const table = Table({
+  columns: [
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'age', label: 'Age', sortable: true },
+  ],
+  data: [
+    { name: 'Alice', age: 28 },
+    { name: 'Bob', age: 34 },
+  ],
+  pageSize: 10,
 });
-
-// All useDeps() requests now go through Axios
-configureHttpClient(createAxiosAdapter(api));
-```
-
-### HTTP Client Plugin (@navios/http Example)
-
-```js
-import { configureHttpClient } from 'kupola';
-import { createNaviosAdapter } from 'kupola/adapters/navios-http';
-import { create } from '@navios/http';
-
-const client = create({ baseURL: '/api' });
-client.interceptors.request.use(config => {
-  config.headers['Authorization'] = `Bearer ${getToken()}`;
-  return config;
-});
-
-configureHttpClient(createNaviosAdapter(client));
+document.body.appendChild(table.element);
 ```
 
 ---
 
-## 📖 Documentation
-
-- [Usage Guide](docs/usage-guide.md) — Getting started and API reference
-- [Integration Guide](INTEGRATION.md) — Framework integration examples
-- [Kupola vs Vue/React](docs/kupola-vs-vue-react.md) — Architecture comparison
-- [Contributing](CONTRIBUTING.md) — How to contribute
-
----
-
-## 🛠️ Development
-
-```bash
-npm install          # Install dependencies
-npm run dev          # Dev server (Vite, hot reload)
-npm run build        # Production build
-npm run lint         # Lint code
-npm run test         # Run tests
-```
+## Core Engine API
 
----
-
-## 🌐 Browser Support
-
-Chrome, Firefox, Safari, Edge (latest)
-
----
-
-<a id="中文"></a>
-## ✨ 核心特性
-
-- **50+ UI 组件** — 按钮、输入框、卡片、模态框、日期选择器、时间选择器、热力图、虚拟列表、统计卡片等
-- **声明式数据依赖** — `useDeps()` 自动缓存、重试、刷新、数据转换
-- **HTTP 客户端插件** — 无缝集成 Axios、@navios/http 或任意 HTTP 客户端，保留拦截器
-- **响应式数据绑定** — 基于 Proxy 的双向绑定，`ref()` / `store()`
-- **双主题** — 暗色优先设计，支持亮色主题切换
-- **11 种品牌色** — 灵感源自中国传统色的可切换品牌主题
-- **响应式** — 适配 PC、平板、手机
-- **无障碍** — 符合 WCAG AA 标准
-- **表单验证** — 内置验证系统，支持自定义规则
-- **零依赖** — 纯 HTML/CSS/JavaScript，minified gzip 约 75 KB
-- **后端无关** — 支持 Flask、Django、FastAPI、Gin、Spring Boot、ASP.NET、Express、Rails、Actix-web 等任何输出 HTML 的后端
-- **TypeScript 支持** — 完整类型定义
-
----
+```javascript
+import { signal, computed, effect, batch, html, render } from '@kupola/kupola';
 
-## 🚀 快速开始
+// Signal — reactive state
+const count = signal(0);
 
-### 脚手架（推荐）
+// Computed — derived value (auto-tracks dependencies)
+const doubled = computed(() => count.value * 2);
 
-一行命令创建配置好的 Kupola 项目：
+// Effect — side effect (auto re-runs)
+effect(() => console.log(`count = ${count.value}, doubled = ${doubled.value}`));
 
-```bash
-npx @kupola/create-kupola
-```
-
-支持 **Static**、**Flask**、**FastAPI**、**Gin** 四种后端模板，自带暗色主题、品牌色和示例页面。
-
-### npm 安装
-
-```bash
-npm install @kupola/kupola
-```
-
-```html
-<link rel="stylesheet" href="node_modules/@kupola/kupola/dist/css/kupola.css">
-<script src="node_modules/@kupola/kupola/dist/kupola.esm.js" type="module"></script>
-```
-
-### CDN 引入
-
-```html
-<!-- ESM（现代浏览器） -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kupola/kupola/dist/css/kupola.css">
-<script src="https://cdn.jsdelivr.net/npm/@kupola/kupola/dist/kupola.esm.js" type="module"></script>
+// Batch — merge multiple updates into one flush
+batch(() => {
+  count.value++;
+  count.value++;
+});
 
-<!-- UMD（传统方式） -->
-<script src="https://cdn.jsdelivr.net/npm/@kupola/kupola/dist/kupola.umd.js"></script>
+// Template + Render — declarative DOM
+const view = () => html`
+  <div class="counter">
+    <p>Count: ${count}</p>
+    <button @click=${() => count.value++}>+1</button>
+  </div>
+`;
+render(view(), document.getElementById('app'));
 ```
 
 ---
 
-## 📦 使用示例
+## Directive System (Declarative HTML)
 
-### 组件（纯 HTML，无需 JS）
+Add interactivity directly in HTML — no build tools required:
 
 ```html
-<button class="ds-btn ds-btn--brand">主要按钮</button>
-<button class="ds-btn ds-btn--outline">描边按钮</button>
-
-<div class="ds-card">
-  <div class="ds-card__header">
-    <h3 class="ds-card__title">卡片标题</h3>
-  </div>
-  <div class="ds-card__body">卡片内容</div>
+<div k-data="{ name: '', items: [], show: true }">
+  <input k-model="name" placeholder="Enter search term">
+  <p k-show="name">Hello, {{ name }}!</p>
+  <ul>
+    <li k-for="item in items" k-text="item"></li>
+  </ul>
+  <button k-on:click="show = !show" k-bind:disabled="!name">
+    <span k-show="show">Hide</span>
+    <span k-show="!show">Show</span>
+  </button>
 </div>
+<script>
+  import { walk } from '@kupola/kupola/directives';
+  walk(document.body);
+</script>
 ```
 
-### 数据绑定
+**Directives Overview**:
 
-```html
-<input type="text" data-bind="user.name:value" placeholder="姓名">
-<span data-bind="user.name:text"></span>
-```
+| Directive | Shorthand | Purpose |
+|-----------|-----------|---------|
+| `k-data` | — | Create a reactive scope |
+| `k-show` | — | Conditional display (`display: none`) |
+| `k-text` | — | Reactive textContent |
+| `k-html` | — | Reactive innerHTML |
+| `k-bind` | `:` | Dynamic attribute binding |
+| `k-on` | `@` | Event listener |
+| `k-model` | — | Two-way input binding |
+| `k-for` | — | List rendering |
 
-```js
-kupolaData.data.user = { name: '张三' };
-kupolaData.data.user.name = '李四';  // 所有绑定元素自动更新
-```
+---
 
-### 声明式数据依赖
+## SSR (Server-Side Rendering)
 
-```html
-<div data-deps="users:fetch:/api/users">
-  <template data-each="users">
-    <span data-bind="item.name:text"></span>
-  </template>
-</div>
-```
+```javascript
+import { signal, html } from '@kupola/kupola';
+import { renderToString } from '@kupola/kupola/server';
 
-```js
-import { useDeps } from 'kupola';
-useDeps({ users: { url: '/api/users', staleTime: 60000 } });
+const title = signal('Hello Server');
+const serverHtml = renderToString(html`<h1>${title}</h1>`);
+// => '<h1>Hello Server<!----></h1>'
+res.send(`<!DOCTYPE html><html><body>${serverHtml}</body></html>`);
 ```
 
-### HTTP 客户端插件（Axios 示例）
+Client-side hydration:
 
-```js
-import { configureHttpClient } from 'kupola';
-import { createAxiosAdapter } from 'kupola/adapters/axios';
-import axios from 'axios';
-
-const api = axios.create({ baseURL: '/api' });
-api.interceptors.request.use(config => {
-  config.headers.Authorization = `Bearer ${getToken()}`;
-  return config;
-});
+```javascript
+import { signal, html } from '@kupola/kupola';
+import { hydrate } from '@kupola/kupola/server';
 
-// 之后所有 useDeps() 请求自动走 Axios + 拦截器
-configureHttpClient(createAxiosAdapter(api));
+const title = signal('Hello Server');
+hydrate(html`<h1>${title}</h1>`, document.body);
+// DOM is not rebuilt — only reactive bindings are attached
 ```
 
 ---
 
-## 📖 文档
-
-- [使用指南](docs/usage-guide.md) — 入门与 API 参考
-- [集成指南](INTEGRATION.md) — 后端框架集成示例
-- [Kupola 与 Vue/React 对比](docs/kupola-vs-vue-react.md) — 架构对比
-- [贡献指南](CONTRIBUTING.md) — 如何参与贡献
+## Components
+
+<details>
+<summary><strong>Overlay & Navigation</strong> (6)</summary>
+
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Modal | `@kupola/kupola/components/modal` | Modal dialog |
+| Dropdown | `@kupola/kupola/components/dropdown` | Dropdown menu |
+| Drawer | `@kupola/kupola/components/drawer` | Side drawer |
+| Tabs | `@kupola/kupola/components/tabs` | Tab panel |
+| Tooltip | `@kupola/kupola/components/tooltip` | Text tooltip |
+| Menu | `@kupola/kupola/components/menu` | Navigation menu |
+
+</details>
+
+<details>
+<summary><strong>Form</strong> (11)</summary>
+
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Input | `@kupola/kupola/components/input` | Text input |
+| Select | `@kupola/kupola/components/select` | Dropdown select |
+| Checkbox | `@kupola/kupola/components/checkbox` | Checkbox |
+| Radio | `@kupola/kupola/components/radio` | Radio button |
+| Switch | `@kupola/kupola/components/switch` | Toggle switch |
+| Slider | `@kupola/kupola/components/slider` | Range slider |
+| NumberInput | `@kupola/kupola/components/numberinput` | Number input |
+| Textarea | `@kupola/kupola/components/textarea` | Multi-line text |
+| Datepicker | `@kupola/kupola/components/datepicker` | Date picker |
+| Timepicker | `@kupola/kupola/components/timepicker` | Time picker |
+| Form | `@kupola/kupola/components/form` | Form container + validation |
+
+</details>
+
+<details>
+<summary><strong>Feedback</strong> (6)</summary>
+
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Dialog | `@kupola/kupola/components/dialog` | Native confirm dialog |
+| Notification | `@kupola/kupola/components/notification` | Notification toast |
+| Message | `@kupola/kupola/components/message` | Lightweight global message |
+| Alert | `@kupola/kupola/components/alert` | Alert banner |
+| Spin | `@kupola/kupola/components/spin` | Loading spinner |
+| Progress | `@kupola/kupola/components/progress` | Progress bar |
+
+</details>
+
+<details>
+<summary><strong>Data Display</strong> (9)</summary>
+
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Table | `@kupola/kupola/components/table` | Data table (sort/filter/paginate/select/edit) |
+| Tree | `@kupola/kupola/components/tree` | Tree view |
+| Calendar | `@kupola/kupola/components/calendar` | Calendar |
+| Carousel | `@kupola/kupola/components/carousel` | Carousel / slider |
+| Timeline | `@kupola/kupola/components/timeline` | Timeline |
+| Collapse | `@kupola/kupola/components/collapse` | Collapse panel |
+| Tag | `@kupola/kupola/components/tag` | Tag |
+| Badge | `@kupola/kupola/components/badge` | Badge |
+| Statcard | `@kupola/kupola/components/statcard` | Stat card |
+
+</details>
+
+<details>
+<summary><strong>Interactive & Utility</strong> (16)</summary>
+
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Pagination | `@kupola/kupola/components/pagination` | Pagination |
+| Breadcrumb | `@kupola/kupola/components/breadcrumb` | Breadcrumb |
+| FileUpload | `@kupola/kupola/components/fileupload` | File upload |
+| DynamicTags | `@kupola/kupola/components/dynamictags` | Dynamic tags |
+| ImagePreview | `@kupola/kupola/components/imagepreview` | Image preview |
+| ColorPicker | `@kupola/kupola/components/colorpicker` | Color picker |
+| VirtualList | `@kupola/kupola/components/virtuallist` | Virtual list |
+| Heatmap | `@kupola/kupola/components/heatmap` | Heatmap |
+| Countdown | `@kupola/kupola/components/countdown` | Countdown timer |
+| Icons | `@kupola/kupola/components/icons` | SVG icon set |
+| Validation | `@kupola/kupola/components/validation` | Validation engine |
+| Avatar | `@kupola/kupola/components/avatar` | Avatar |
+| Divider | `@kupola/kupola/components/divider` | Divider |
+| Skeleton | `@kupola/kupola/components/skeleton` | Skeleton screen |
+| Empty | `@kupola/kupola/components/empty` | Empty state |
+| Kbd | `@kupola/kupola/components/kbd` | Keyboard key |
+
+</details>
 
 ---
 
-## 🛠️ 开发
+## TypeScript
 
-```bash
-npm install          # 安装依赖
-npm run dev          # 开发服务器（Vite，热更新）
-npm run build        # 生产构建
-npm run lint         # 代码检查
-npm run test         # 运行测试
+Full type definitions included out of the box:
+
+```typescript
+import type { Modal, ModalOptions } from '@kupola/kupola/components/modal';
+import type { Table, TableOptions, TableColumn } from '@kupola/kupola/components/table';
+
+const options: ModalOptions = {
+  title: 'Confirm',
+  content: 'Are you sure you want to delete?',
+  onConfirm: () => console.log('confirmed'),
+};
 ```
 
 ---
 
-## 🌐 浏览器支持
+## Browser Support
 
-Chrome、Firefox、Safari、Edge（最新版本）
+- Chrome / Edge >= 88
+- Firefox >= 78
+- Safari >= 14
+- IE is not supported
 
 ---
 
-## 🤝 Contributing / 贡献
+## Documentation
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+- 📖 [Integration Guide](./INTEGRATION.md) — CDN / SSR / Vite / Webpack / React / Vue
+- 🤝 [Contributing Guide](./CONTRIBUTING.md) — Dev setup & code standards
+- 📋 [Changelog](./CHANGELOG.md)
+- 📄 [MIT License](./LICENSE)
 
 ---
 
-## 🙏 Acknowledgments / 致谢
-
-Kupola is built with the help of these excellent open-source tools:
+## Ecosystem
 
-**Build & Dev Tooling:**
-- [Vite](https://vitejs.dev/) — Next generation frontend tooling
-- [Rollup](https://rollupjs.org/) — ES module bundler
-- [ESLint](https://eslint.org/) — JavaScript linter
-- [Prettier](https://prettier.io/) — Code formatter
-- [Jest](https://jestjs.io/) — JavaScript testing framework
-
-**HTTP Client Adapters (optional, user-installed):**
-- [Axios](https://axios-http.com/) — Promise based HTTP client
-- [@navios/http](https://www.npmjs.com/package/@navios/http) — Lightweight fetch-based Axios replacement
+| Project | Description |
+|---------|-------------|
+| `@kupola/kupola` | Core engine + 48 UI components |
+| `create-kupola` | Project scaffolding CLI |
+| `his-sys` | HIS medical system built on Kupola |
 
 ---
 
-## 📄 License
-
-[MIT](LICENSE) © Kupola Team
+<p align="center">
+  <strong>Kupola</strong> — Zero framework dependencies. Declarative UI. Import only what you need.
+</p>