@kupola/kupola 1.2.0 → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KUPOLA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,286 +1,330 @@
-# Kupola
-
-A lightweight UI toolkit for any web project. No heavy frontend frameworks required. Works seamlessly with Flask, Django, Gin, Spring Boot, ASP.NET Core, Express, Ruby on Rails, and any backend framework that outputs HTML.
-
-## Features
-
-- **50+ Components**: Buttons, inputs, cards, modals, datepickers, timepickers, heatmap, virtual list, stat cards, image components, and more
-- **Dual Themes**: Dark-first design with light theme support
-- **11 Brand Colors**: Switchable brand colors
-- **Responsive Design**: Works on PC, Pad, and Phone
-- **Accessibility**: WCAG AA compliant
-- **Form Validation**: Built-in validation with custom rules
-- **Data Binding**: Two-way data binding system (Proxy-based)
-- **No Dependencies**: Pure HTML/CSS/JavaScript
-- **Multi-language Support**: Helper functions for Python, Go, Java, C#, Node.js, Ruby
-
-## Quick Start
-
-### 1. Copy Files
-
-Copy the `kupola` directory to your project:
-
-```
-your-project/
-├── kupola/
-│   ├── css/
-│   ├── js/
-│   └── icons/
-└── index.html
-```
-
-### 2. Include CSS
-
-```html
-<link rel="stylesheet" href="kupola/css/kupola.css">
-```
-
-### 3. Include JavaScript
-
-```html
-<script src="kupola/js/kupola-core.js"></script>
-```
-
-### 4. Start Using Components
-
-```html
-<button class="ds-btn ds-btn--brand">Click Me</button>
-<input type="text" class="ds-input" placeholder="Enter text">
-<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>
-```
-
-## Framework Integration
-
-### Python (Flask/Django)
-
-```python
-from kupola import button, card
-
-html = card("Welcome", "Hello Kupola!", "") + button("Submit", "brand", "md")
-```
-
-### Go (Gin/Echo)
-
-```go
-import "kupola"
-
-html := kupola.Card("Welcome", "Hello Kupola!", "") + kupola.Button("Submit", "brand", "md")
-```
-
-### Java (Spring Boot)
-
-```java
-import com.kupola.Kupola;
-
-String html = Kupola.card("Welcome", "Hello Kupola!", "") + Kupola.button("Submit", "brand", "md");
-```
-
-### C# (ASP.NET Core)
-
-```csharp
-using Kupola;
-
-string html = Components.Card("Welcome", "Hello Kupola!", "") + Components.Button("Submit", "brand", "md");
-```
-
-### Node.js (Express/Koa)
-
-```javascript
-import { button, card } from './kupola/utils/kupola.js';
-
-const html = card('Welcome', 'Hello Kupola!', '') + button('Submit', 'brand', 'md');
-```
-
-### Ruby (Ruby on Rails)
-
-```ruby
-require './utils/kupola.rb'
-
-html = Kupola.card('Welcome', 'Hello Kupola!', '') + Kupola.button('Submit', 'brand', 'md')
-```
-
-## Basic Usage Examples
-
-### Buttons
-
-```html
-<button class="ds-btn ds-btn--brand">Primary</button>
-<button class="ds-btn ds-btn--secondary">Secondary</button>
-<button class="ds-btn ds-btn--outline">Outline</button>
-<button class="ds-btn ds-btn--ghost">Ghost</button>
-<button class="ds-btn ds-btn--danger">Danger</button>
-```
-
-### Inputs
-
-```html
-<input type="text" class="ds-input" placeholder="Text input">
-<input type="password" class="ds-input" placeholder="Password">
-<input type="email" class="ds-input" placeholder="Email">
-<textarea class="ds-textarea" placeholder="Textarea"></textarea>
-```
-
-### Cards
-
-```html
-<div class="ds-card">
-    <div class="ds-card__header">
-        <h3 class="ds-card__title">Card Title</h3>
-        <p class="ds-card__subtitle">Subtitle</p>
-    </div>
-    <div class="ds-card__body">Card content goes here</div>
-    <div class="ds-card__footer">Footer actions</div>
-</div>
-```
-
-### Forms
-
-```html
-<form class="ds-form">
-    <div class="ds-form-item">
-        <label class="ds-form-item__label">Name</label>
-        <input type="text" class="ds-input" placeholder="Enter name">
-    </div>
-    <div class="ds-form-item">
-        <label class="ds-form-item__label">Email</label>
-        <input type="email" class="ds-input" data-validate="email" placeholder="Enter email">
-    </div>
-    <button type="submit" class="ds-btn ds-btn--brand">Submit</button>
-</form>
-```
-
-### Data Binding
-
-```html
-<input type="text" data-bind="user.name:value" placeholder="Name">
-<span data-bind="user.name:text"></span>
-<input type="checkbox" data-bind="user.active:checked">
-```
-
-```javascript
-kupolaData.data.user = { name: 'John', active: true };
-kupolaData.data.user.name = 'Jane';  // Auto updates all bound elements
-```
-
-### Theme Switching
-
-```javascript
-setTheme('light');   // Switch to light theme
-setTheme('dark');    // Switch to dark theme
-setBrand('zengqing'); // Set brand color to 曾青
-```
-
-## Project Structure
-
-```
-kupola/
-├── css/                    # CSS stylesheets
-│   ├── kupola.css          # Main CSS bundle
-│   ├── components.css      # Component styles
-│   ├── components-ext.css  # Extended component styles
-│   ├── theme-dark.css      # Dark theme tokens
-│   ├── theme-light.css     # Light theme tokens
-│   └── ...                 # Other stylesheets
-├── js/                     # JavaScript modules (40+)
-│   ├── kupola-core.js      # Core framework
-│   ├── kupola-lifecycle.js # Lifecycle management
-│   ├── kupola-devtools.js  # Development tools
-│   ├── component.js        # Base component class
-│   ├── router.js           # Client-side router
-│   ├── http.js             # HTTP client
-│   ├── data-bind.js        # Data binding
-│   ├── validation.js       # Form validation
-│   ├── theme.js            # Theme/brand switching
-│   └── ...                 # UI components
-├── icons/                  # 120+ SVG icons
-├── dist/                   # Build output
-│   ├── kupola.esm.js       # ES Module format
-│   ├── kupola.cjs.js       # CommonJS format
-│   ├── kupola.umd.js       # UMD format
-│   └── types/kupola.d.ts   # TypeScript types
-├── src/                    # Build entry points
-├── utils/                  # Multi-language utility functions
-│   ├── kupola.py           # Python component generation
-│   ├── kupola.go           # Go component generation
-│   ├── Kupola.java         # Java component generation
-│   ├── Kupola.cs           # C# component generation
-│   ├── kupola.js           # Node.js component generation
-│   └── kupola.rb           # Ruby component generation
-├── templates/              # HTML templates
-│   ├── base.html           # Base template
-│   └── base_dashboard.html # Dashboard base template
-├── dashboard/              # Dashboard template
-├── casepages/              # Component showcase pages
-├── test/                   # Test files
-├── examples/               # Usage examples
-├── docs/                   # Documentation
-├── INTEGRATION.md          # Integration guide
-└── package.json            # Build scripts
-```
-
-## Build
-
-```bash
-cd kupola
-npm install
-npm run build    # Production build (Vite)
-npm run build:rollup  # Alternative build (Rollup)
-npm run dev      # Development server
-```
-
-## Documentation
-
-- [Integration Guide](INTEGRATION.md) - Framework integration examples
-- [API Documentation](docs/api.md) - API reference
-- [showcase.html](dashboard/showcase.html) - Interactive component showcase
-- [Case Pages](casepages/) - Component usage examples
-
-## Browser Support
-
-Chrome, Firefox, Safari, Edge (latest versions)
-
-## License
-
-MIT License
-
-## Migration Notice
-
-This project was previously known as **Nimbus Design System**. It has been renamed to **Kupola** with the following changes:
-
-### Name Changes
-
-| Old Name | New Name |
-|----------|----------|
-| `NimbusComponent` | `KupolaComponent` |
-| `NimbusHttp` | `KupolaHttp` |
-| `NimbusRouter` | `KupolaRouter` |
-| `NimbusLifecycle` | `KupolaLifecycle` |
-| `window.nimbusData` | `window.kupolaData` |
-| `window.nimbusRegistry` | `window.kupolaRegistry` |
-
-### File Changes
-
-| Old Path | New Path |
-|----------|----------|
-| `js/nimbus-core.js` | `js/kupola-core.js` |
-| `js/nimbus-lifecycle.js` | `js/kupola-lifecycle.js` |
-| `js/nimbus-devtools.js` | `js/kupola-devtools.js` |
-| `css/nimbus.css` | `css/kupola.css` |
-| `types/nimbus.d.ts` | `types/kupola.d.ts` |
-| `dist/nimbus.esm.js` | `dist/kupola.esm.js` |
-| `dist/nimbus.cjs.js` | `dist/kupola.cjs.js` |
-| `dist/nimbus.umd.js` | `dist/kupola.umd.js` |
-
-### Removed Files
-
-- `build.js` / `watch.js` - Legacy build scripts (replaced by Vite)
-- `dev-server.js` - Unused development server
-- `DOCS.md` - Outdated documentation
-- `components/` - Legacy HTML components
-- `common/` - Empty directory
-- Temporary scripts: `rename-project.cjs`, `fix-remaining.cjs`, etc.
+# 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-88%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)
+- [中文](#中文)
+
+---
+
+<a id="english"></a>
+## ✨ 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, ~88 KB 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
+
+---
+
+## 🚀 Quick Start
+
+### 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>
+```
+
+---
+
+## 📦 Usage
+
+### Components (HTML-only, no JS needed)
+
+```html
+<button class="ds-btn ds-btn--brand">Primary</button>
+<button class="ds-btn ds-btn--outline">Outline</button>
+
+<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>
+```
+
+### 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;
+});
+
+// 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));
+```
+
+---
+
+## 📖 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
+```
+
+---
+
+## 🌐 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，gzip 后约 88 KB
+- **后端无关** — 支持 Flask、Django、FastAPI、Gin、Spring Boot、ASP.NET、Express、Rails、Actix-web 等任何输出 HTML 的后端
+- **TypeScript 支持** — 完整类型定义
+
+---
+
+## 🚀 快速开始
+
+### 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>
+
+<!-- UMD（传统方式） -->
+<script src="https://cdn.jsdelivr.net/npm/@kupola/kupola/dist/kupola.umd.js"></script>
+```
+
+---
+
+## 📦 使用示例
+
+### 组件（纯 HTML，无需 JS）
+
+```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>
+```
+
+### 数据绑定
+
+```html
+<input type="text" data-bind="user.name:value" placeholder="姓名">
+<span data-bind="user.name:text"></span>
+```
+
+```js
+kupolaData.data.user = { name: '张三' };
+kupolaData.data.user.name = '李四';  // 所有绑定元素自动更新
+```
+
+### 声明式数据依赖
+
+```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 客户端插件（Axios 示例）
+
+```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;
+});
+
+// 之后所有 useDeps() 请求自动走 Axios + 拦截器
+configureHttpClient(createAxiosAdapter(api));
+```
+
+---
+
+## 📖 文档
+
+- [使用指南](docs/usage-guide.md) — 入门与 API 参考
+- [集成指南](INTEGRATION.md) — 后端框架集成示例
+- [Kupola 与 Vue/React 对比](docs/kupola-vs-vue-react.md) — 架构对比
+- [贡献指南](CONTRIBUTING.md) — 如何参与贡献
+
+---
+
+## 🛠️ 开发
+
+```bash
+npm install          # 安装依赖
+npm run dev          # 开发服务器（Vite，热更新）
+npm run build        # 生产构建
+npm run lint         # 代码检查
+npm run test         # 运行测试
+```
+
+---
+
+## 🌐 浏览器支持
+
+Chrome、Firefox、Safari、Edge（最新版本）
+
+---
+
+## 🤝 Contributing / 贡献
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+---
+
+## 🙏 Acknowledgments / 致谢
+
+Kupola is built with the help of these excellent open-source tools:
+
+**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
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © Kupola Team