@kupola/kupola 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,130 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-07-09
+
+### Added
+
+- **Architecture**: Added `package.json` exports field for ES Module support
+- **Architecture**: Added `vite.config.js` for modern Vite/Rolldown build support
+- **Architecture**: Added `.eslintrc.cjs` with comprehensive linting rules
+- **Architecture**: Added `.prettierrc` for consistent code formatting
+- **Architecture**: Added `jest.config.cjs` and test setup for unit testing
+- **Architecture**: Added comprehensive test scripts (`test`, `test:watch`, `test:coverage`)
+- **Architecture**: Added lint scripts (`lint`, `lint:fix`) and format script
+- **Security**: Added XSS protection utility (`escapeHtml`, `sanitize`)
+- **Security**: Added CSRF protection mechanism
+- **Error Handling**: Added unified error boundary and global error handler
+- **Performance**: Added performance monitoring utility (`KupolaPerformance`)
+- **Components**: Converted 7 functional components to class-based (Dropdown, Select, ColorPicker, Datepicker, Timepicker, Tooltip, SlideCaptcha)
+- **HTTP**: Added `cancelAllRequests()` method for batch request cancellation
+- **HTTP**: Fixed `cancelRequest()` to support all HTTP methods
+
+### Changed
+
+- **package.json**: Added `type: module` for ES Module compatibility
+- **package.json**: Updated build scripts to support both Rollup and Vite
+- **package.json**: Added dev dependencies (vite, eslint, prettier, jest)
+- **KupolaHttp**: Fixed `response.ok` check for proper error handling
+- **KupolaComponent**: Fixed `setState/setProps` to await lifecycle updates
+- **KupolaLifecycle**: Fixed `onError` property/method name conflict
+- **Data Bind**: Unified `createReactive()` and `wrapReactive()` implementations
+- **Composition API**: Fixed computed() circular reference issue
+- **Dialog**: Fixed incomplete event listener cleanup
+
+### Fixed
+
+- **Memory Leaks**: Fixed global event listeners in all components using GlobalEventManager
+- **Memory Leaks**: Fixed Modal, ImagePreview, Heatmap, Datepicker listener cleanup
+- **Memory Leaks**: Fixed SlideCaptcha touch/mouse event cleanup
+- **Performance**: Fixed wrapReactive() duplicate Proxy creation using WeakMap cache
+- **Initialization**: Added `__kupolaInitialized` flags to prevent duplicate initialization
+
+## [1.1.1] - 2026-07-07
+
+### Added
+
+- **Components**: Added Statistic Card (`ds-statcard`) with number animation, trend indicators, and progress bar
+- **Components**: Added Image (`ds-image`) with placeholder, fallback, and error states
+- **Components**: Added Image List (`ds-image-list`) with grid layout and selection
+- **Components**: Added Image Preview (`ds-image-preview`) with full-screen viewer
+- **Components**: Added Tag (`ds-tag`) with closable functionality
+- **File Upload**: Added file size limit (`data-max-size`), multi-file limit (`data-max-count`), error handling, image preview, and upload progress
+- **Form Validation**: Enhanced validation to support DatePicker, Dropdown, and FileUpload components; added success state icons; added duplicate submission prevention
+- **Heatmap**: Fixed color display issue with green gradient; added horizontal scroll layout; fixed mock data generation
+
+### Changed
+
+- **Heatmap**: Changed from vertical to horizontal column layout for better visual alignment
+- **Virtual List**: Fixed mouse wheel scrolling support for both vertical and horizontal modes
+- **File Upload**: Enhanced disabled state with distinct visual styling
+- **Components CSS**: Renamed `components-new.css` to `components-ext.css`
+
+### Fixed
+
+- **File Upload**: Fixed duplicate file selector popup caused by event bubbling
+- **Heatmap**: Fixed "0 contributions" display by including all dates in mock data
+- **Sidebar**: Fixed missing icons for Data and Data Viz navigation items
+- **Heatmap**: Fixed color visibility in dark theme with improved green gradient colors
+
+## [1.1.0] - 2026-07-07
+
+### Added
+
+- **Components**: Added 26+ new components including Heatmap, Virtual List, Slide Captcha, Countdown, Carousel, Drawer, Color Picker, Image Preview, Notification, Message, Collapse, Dynamic Tags, Timepicker, Number Input, Progress Circle, Slider, Checkbox, Radio, Switch, Badge, Timeline, Divider, Empty, Spin, etc.
+- **Heatmap Color Customization**: Added `data-color` attribute support for custom heatmap colors
+- **Brand Picker Auto-create**: Added automatic brand picker popup creation in theme.js, eliminating duplicate inline code
+- **Form Validation**: Added comprehensive form validation system with multiple rules (required, email, phone, url, min, max, pattern)
+- **Tooltip System**: Added custom tooltip system with `data-title` attribute and mouse-follow positioning
+- **Data Binding**: Added two-way data binding system with event bus
+
+### Changed
+
+- **Default Brand Color**: Changed default brand color from 翠绿 (#32F08C) to 曾青 (#535164)
+- **Brand Color API**: Renamed `setBrandColor()` to `setBrand()` for consistency
+- **Heatmap**: Fixed date range mismatch issue, updated mock data generation logic
+- **Dashboard Layout**: Fixed header display issues, improved scroll container handling
+- **Input Components**: Removed inner input borders for Date Picker, Time Picker, and Number Input
+
+### Fixed
+
+- **Event Listener Duplication**: Added execution flags (`window.__nimbus*Initialized`) to prevent duplicate event binding in theme.js, validation.js, and tooltip.js
+- **Form Validation**: Fixed `.ds-dropdown` class name error in getValue(), changed to `.ds-select`
+- **Heatmap Colors**: Fixed cell color display issue by adding `!important` to CSS styles
+- **Brand Picker**: Fixed popup not showing on page load by checking `document.readyState`
+- **Accessibility**: Improved icon visibility in both dark and light themes using CSS filter
+- **Tooltip Positioning**: Fixed tooltip being blocked by mouse cursor, positioned at bottom-right
+
+## [1.0.0] - 2026-07-03
+
+### Added
+
+- **Components**: Added 14 components (buttons, cards, forms, tables, dialogs, pagination, stat cards, nav lists, file trees, alerts, tags, tabs, modals, avatars)
+- **Themes**: Added dark and light themes with CSS variables
+- **Brand Colors**: Added 11 brand colors (翠绿, 雄黄, 姜黄, 蓝绿, 孔雀蓝, 玫瑰紫, 柿红, 紫云, 山茶红, 曾青, 柔蓝)
+- **Dashboard**: Added complete dashboard layout framework
+- **Templates**: Added Flask base templates (base.html, base_dashboard.html)
+- **Python Utilities**: Added nimbus.py with component generation functions
+- **SVG Sprite**: Added icons.svg sprite file for optimized icon loading
+- **Documentation**: Added comprehensive README with usage examples
+
+### Changed
+
+- **Icons**: Updated icon colors to match Nimbus design system
+- **CSS**: Refactored CSS into modular files (nimbus.css, brand-themes.css, states.css, utilities.css)
+
+### Removed
+
+- N/A
+
+## [0.1.0] - 2026-06-01
+
+### Added
+
+- Initial project setup
+- Core CSS variables (colors_and_type.css)
+- Basic components (buttons, cards, forms)

package/INTEGRATION.md

@@ -0,0 +1,440 @@
+# Nimbus Design System - Integration Guide
+
+## Table of Contents
+
+1. [Flask Integration](#flask-integration)
+2. [Django Integration](#django-integration)
+3. [Static Site Integration](#static-site-integration)
+4. [Python Helper Functions](#python-helper-functions)
+5. [Production Deployment](#production-deployment)
+
+---
+
+## Flask Integration
+
+### Step 1: Copy Files
+
+Copy the `nimbus` directory to your Flask project's `static` folder:
+
+```
+your-flask-app/
+├── static/
+│   └── nimbus/
+│       ├── css/
+│       ├── js/
+│       ├── icons/
+│       └── utils/
+├── templates/
+└── app.py
+```
+
+### Step 2: Create Base Template
+
+Create `templates/base.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% block title %}Nimbus{% endblock %}</title>
+    
+    <!-- Nimbus CSS -->
+    <link rel="stylesheet" href="{{ url_for('static', filename='nimbus/css/nimbus.min.css') }}">
+</head>
+<body data-theme="dark">
+    {% block content %}{% endblock %}
+    
+    <!-- Nimbus JS -->
+    <script src="{{ url_for('static', filename='nimbus/js/nimbus.min.js') }}"></script>
+    <script>
+        initTheme();
+        initTooltip();
+        initDatepickers();
+        initFileUploads();
+        initValidation();
+    </script>
+    {% block scripts %}{% endblock %}
+</body>
+</html>
+```
+
+### Step 3: Use Components in Templates
+
+Create `templates/index.html`:
+
+```html
+{% extends 'base.html' %}
+
+{% block title %}Dashboard{% endblock %}
+
+{% block content %}
+<div class="ds-page-header">
+    <div class="ds-page-header__left">
+        <h1 class="ds-page-header__title">Welcome</h1>
+        <p class="ds-page-header__subtitle">This is your dashboard</p>
+    </div>
+    <div class="ds-page-header__right">
+        <button class="ds-btn ds-btn--brand">Get Started</button>
+    </div>
+</div>
+
+<div class="ds-card">
+    <div class="ds-card__body">
+        <form class="ds-form" style="display: flex; flex-direction: column; gap: 16px; width: 300px;">
+            <input type="text" class="ds-input" data-validate="required,email" placeholder="Email">
+            <input type="password" class="ds-input" data-validate="required,min:6" placeholder="Password">
+            <button type="submit" class="ds-btn ds-btn--brand">Login</button>
+        </form>
+    </div>
+</div>
+{% endblock %}
+```
+
+### Step 4: Use Python Helper Functions
+
+Import the helper functions in your Flask app:
+
+```python
+from utils.nimbus import *
+
+@app.route('/')
+def index():
+    return render_template('index.html', 
+                           btn=btn,
+                           card=card,
+                           input_field=input_field)
+```
+
+In your template:
+
+```html
+{{ btn('Primary Button', variant='primary') }}
+{{ card(title='Card Title', body='Card content') }}
+```
+
+---
+
+## Django Integration
+
+### Step 1: Copy Files
+
+Copy the `nimbus` directory to your Django project's `static` folder:
+
+```
+your-django-app/
+├── your_app/
+│   ├── static/
+│   │   └── nimbus/
+│   │       ├── css/
+│   │       ├── js/
+│   │       ├── icons/
+│   │       └── utils/
+│   └── templates/
+└── settings.py
+```
+
+### Step 2: Configure Static Files
+
+In `settings.py`:
+
+```python
+STATIC_URL = '/static/'
+STATICFILES_DIRS = [
+    os.path.join(BASE_DIR, 'your_app/static'),
+]
+```
+
+### Step 3: Create Base Template
+
+Create `templates/base.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% block title %}Nimbus{% endblock %}</title>
+    
+    <!-- Nimbus CSS -->
+    <link rel="stylesheet" href="{% static 'nimbus/css/nimbus.min.css' %}">
+</head>
+<body data-theme="dark">
+    {% block content %}{% endblock %}
+    
+    <!-- Nimbus JS -->
+    <script src="{% static 'nimbus/js/nimbus.min.js' %}"></script>
+    <script>
+        initTheme();
+        initTooltip();
+        initDatepickers();
+        initFileUploads();
+        initValidation();
+    </script>
+    {% block scripts %}{% endblock %}
+</body>
+</html>
+```
+
+### Step 4: Use Components in Templates
+
+Create `templates/index.html`:
+
+```html
+{% extends 'base.html' %}
+
+{% block title %}Dashboard{% endblock %}
+
+{% block content %}
+<div class="ds-page-header">
+    <div class="ds-page-header__left">
+        <h1 class="ds-page-header__title">Welcome</h1>
+        <p class="ds-page-header__subtitle">This is your dashboard</p>
+    </div>
+</div>
+{% endblock %}
+```
+
+### Step 5: Use Python Helper Functions
+
+Create a custom template tag in `your_app/templatetags/nimbus_tags.py`:
+
+```python
+from django import template
+from your_app.static.nimbus.utils.nimbus import *
+
+register = template.Library()
+
+@register.simple_tag
+def ds_btn(text, variant='brand'):
+    return btn(text, variant)
+
+@register.simple_tag
+def ds_card(title, body):
+    return card(title, body)
+
+@register.simple_tag
+def ds_input(placeholder, validate=''):
+    return input_field(placeholder, validate)
+```
+
+In your template:
+
+```html
+{% load nimbus_tags %}
+
+{% ds_btn 'Primary Button' 'primary' %}
+{% ds_card 'Card Title' 'Card content' %}
+{% ds_input 'Email' 'required,email' %}
+```
+
+---
+
+## Static Site Integration
+
+### Step 1: Copy Files
+
+Copy the `nimbus` directory to your static site:
+
+```
+your-static-site/
+├── nimbus/
+│   ├── css/
+│   ├── js/
+│   └── icons/
+└── index.html
+```
+
+### Step 2: Create HTML Page
+
+Create `index.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Nimbus Dashboard</title>
+    
+    <!-- Nimbus CSS -->
+    <link rel="stylesheet" href="nimbus/css/nimbus.min.css">
+</head>
+<body data-theme="dark">
+    <div class="ds-page-header">
+        <div class="ds-page-header__left">
+            <h1 class="ds-page-header__title">Welcome</h1>
+        </div>
+    </div>
+    
+    <!-- Nimbus JS -->
+    <script src="nimbus/js/nimbus.min.js"></script>
+    <script>
+        initTheme();
+        initTooltip();
+        initDatepickers();
+        initFileUploads();
+        initValidation();
+    </script>
+</body>
+</html>
+```
+
+---
+
+## Python Helper Functions
+
+### Available Functions
+
+The `nimbus.py` file provides helper functions for generating component HTML:
+
+| Function | Description |
+|----------|-------------|
+| `btn(text, variant='brand', size='md', icon='')` | Button component |
+| `card(title, body, footer='')` | Card component |
+| `input_field(placeholder, validate='')` | Input component |
+| `textarea(placeholder)` | Textarea component |
+| `select(options, selected='')` | Select component |
+| `checkbox(label, checked=False)` | Checkbox component |
+| `radio(name, label, checked=False)` | Radio component |
+| `switch(checked=False)` | Switch component |
+| `badge(text, variant='default')` | Badge component |
+| `alert(text, variant='info')` | Alert component |
+| `tabs(tabs)` | Tabs component |
+| `progress_bar(percent, indeterminate=False)` | Progress bar |
+| `progress_circle(value, label='')` | Progress circle |
+| `slider(label, value=50)` | Slider component |
+| `datepicker(placeholder='Select date')` | Datepicker component |
+| `fileupload(accept='')` | File upload component |
+| `timeline(items)` | Timeline component |
+| `avatar(image='', initials='')` | Avatar component |
+| `breadcrumb(items)` | Breadcrumb component |
+
+### Usage Example
+
+```python
+from utils.nimbus import *
+
+# Generate HTML
+html = btn('Submit', variant='primary') + \
+       card('User Profile', 'User information')
+
+# In Flask template
+return render_template('page.html', html=html)
+```
+
+---
+
+## Production Deployment
+
+### Step 1: Build Files
+
+Run the build script to generate compressed files:
+
+```bash
+cd nimbus
+npm run build
+```
+
+### Step 2: Use Compressed Files
+
+In production, use the minified files from the `dist/` directory:
+
+```html
+<!-- CSS -->
+<link rel="stylesheet" href="nimbus/dist/css/nimbus.min.css">
+
+<!-- JS -->
+<script src="nimbus/dist/js/nimbus.min.js"></script>
+```
+
+### Step 3: CDN Deployment (Optional)
+
+Upload the `dist/` directory to a CDN and reference it:
+
+```html
+<link rel="stylesheet" href="https://cdn.example.com/nimbus/css/nimbus.min.css">
+<script src="https://cdn.example.com/nimbus/js/nimbus.min.js"></script>
+```
+
+### Step 4: Browser Caching
+
+Set appropriate caching headers for static assets:
+
+- CSS/JS files: `Cache-Control: public, max-age=31536000`
+- Icon files: `Cache-Control: public, max-age=31536000`
+
+---
+
+## Dashboard Integration
+
+### Basic Dashboard Layout
+
+```html
+<div class="ds-dashboard">
+    <header class="ds-dashboard__header">
+        <!-- Header content -->
+    </header>
+    <div class="ds-dashboard__body">
+        <aside class="ds-dashboard__sidebar">
+            <!-- Sidebar content -->
+        </aside>
+        <main class="ds-dashboard__content">
+            <!-- Main content -->
+        </main>
+    </div>
+    <footer class="ds-dashboard__footer">
+        <!-- Footer content -->
+    </footer>
+</div>
+```
+
+### Complete Dashboard Example
+
+See `nimbus/dashboard/dashboard.html` for a complete example.
+
+---
+
+## Tips
+
+1. **Theme Switching**: Use `setTheme('light')` or `setTheme('dark')` to switch themes
+2. **Brand Color**: Use `setBrand('zengqing')` to switch brand colors (default: 曾青 #535164)
+3. **Validation**: Add `data-validate` attributes to form fields
+4. **Tooltip**: Add `data-title` attributes to elements for tooltips
+5. **Responsive**: The design system automatically adapts to different screen sizes
+
+---
+
+## Troubleshooting
+
+### Icons Not Displaying
+
+Ensure the icons path is correct. The icons should be in `nimbus/icons/` directory.
+
+### Theme Not Applying
+
+Make sure the `data-theme` attribute is set on the `<body>` element.
+
+### JavaScript Not Working
+
+Check that all JS files are loaded in the correct order:
+
+1. `icons.js`
+2. `theme.js`
+3. `tooltip.js`
+4. `datepicker.js`
+5. `fileupload.js`
+6. `validation.js`
+7. `data-bind.js`
+
+### CSS Not Loading
+
+Verify the CSS path is correct and the file exists.
+
+---
+
+## Support
+
+For issues or feature requests, please refer to the project documentation or create an issue.