@ticatec/topside-elements 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 1.0.0 — 首个公开版本
+
+### 新增
+- **DataTable 合计行**：列 `summary`（`sum` / `avg` / `count` / `min` / `max` / 自定义函数 / `'label'`）与 `summaryFormatter`；表格 `summaryLabel`、`summaryValues`（分页时传服务端全量合计）。合计行贴底、横向随数据滚动，冻结列 / 操作列同步显示。详见 `data_table/README_CN.md`「合计行」。
+- i18n 新键 `dataTable.summaryLabel`（默认 "Total"）。应用自己的语言包需补上，如 zh-CN：`"summaryLabel": "合计"`。
+
+### 修复
+- **NumberInput**（NumberEditor / NumberRange / UnitNumberEditor 共用）：Ctrl/⌘ + A/C/V/X/Z 等组合键不再被拦截；Enter / Esc / Home / End 等具名键放行；粘贴带千分位或空白的数字（`1,234.50`）会自动清理；可以直接输入以 `-` 开头的负数；非法输入的回退此前从未生效，已修正。
+- **MemoEditor**：`onblur` 现在会触发（此前被解构后没有绑定到 textarea）。
+- **PromptsTextEditor**：`onchange` 现在会触发——手输内容在原生 change（失焦 / 回车）时提交，选中候选词和清空立即提交（此前从不触发）。
+- **清空统一触发 `onchange`**：点清空按钮（及 CommonPicker 上的 Backspace / Delete 清空）现在所有编辑器都会通知 `onchange`，此前只有 Lookup / OptionsMultiSelect / ColorPicker / CascadeOptionSelect 会，其余只改绑定值，靠 `onchange` 收值的宿主（topside-datatable 行内编辑、topside-property）会漏掉"清空"。清空后收到的值：
+
+  | 编辑器 | 值 |
+  |---|---|
+  | TextEditor / NumberEditor / UnitNumberEditor / PromptsTextEditor / DatePicker / DateTimePicker / TimeEditor / ColorPicker | `undefined` |
+  | PasswordEditor / MemoEditor | `''` |
+  | OptionsSelect / InputOptionsSelect / LookupEditor / CascadeOptionSelect | `null`（选择时交回选项对象，清空表示无选中项） |
+  | OptionsMultiSelect | `[]` |
+
+  TimeEditor 清空时立即通知，之后失焦不再重复触发。
+- **UnitNumberEditor**：`onchange` 此前从不触发（通知逻辑整段被注释掉），现在与 NumberEditor 一致，输入和失焦时通知标准单位下的值。
+- **MemoEditor**：`onchange` 现在交回新值（字符串），此前透传的是原生 change 事件对象。
+- **plain 变体错误态**：`.topside-form-editor.plain.error` 现在显示红色底线（此前被 `.plain` 覆盖成透明）；删除无效的 `&.focus-within` 规则。
+- **FlexForm**：根元素 class 由 `topside-flexi` 改为 `flex-form`，组件自带的 flex 布局此前从未生效，现在生效。
+- **浮层**（Toast / MessageBox / ContextMenu / Indicator）：修复控制器与面板循环引用导致的 `Cannot access 'XxxPanel' before initialization`。
+
+### 行为变化（升级注意）
+- FlexForm 现在按 flex 换行布局；若外部样式依赖旧的 `.topside-flexi` class，需要改为 `.flex-form`。
+- NumberInput 不再对被拦截的按键 `stopPropagation`，外层可以收到 Enter / Esc；需要判断是否被拦截请看 `event.defaultPrevented`。
+- MemoEditor 的 `onchange` 参数由 DOM `Event` 改为字符串值；各编辑器清空时都会多一次 `onchange` 调用（见上表）。
+- 内部 API `createSingletonMounter` 改为接收组件的 thunk：`createSingletonMounter(() => Panel)`。
+
+### 依赖
+- peer `@ticatec/i18n` 放宽为 `^0.5.0 || ^0.6.0`（0.6.0 修复了异步加载资源后已持有的文案节点仍停在缺失状态的问题，推荐使用）。
+
+### 构建
+- `svelte.config.js` 删除误放的 vite 配置 `plugins: [sveltekit()]`：加载配置时会执行 SvelteKit 的 vite 插件，导致 `svelte-kit sync` / `svelte-check` / `svelte-package` 在 Linux CI 上内存耗尽、在本机也明显变慢（删除后均约 10 秒完成）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 henryfeng
+
+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

@@ -0,0 +1,308 @@
+# Topside Element
+
+[![npm version](https://badge.fury.io/js/%40ticatec%2Ftopside-elements.svg)](https://badge.fury.io/js/%40ticatec%2Ftopside-elements)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A comprehensive enterprise-grade UI component library built with Svelte 5, designed for modern web applications.
+
+[中文文档](./README_CN.md)
+
+## Features
+
+✨ **Enterprise-Grade Components** - Complete set of components for business applications  
+🎨 **Theme System** - CSS variables-based theming with customizable design tokens  
+📱 **Responsive Design** - Mobile-first responsive components  
+🌍 **Internationalization** - Built-in i18n support with English and Chinese resources  
+🎯 **TypeScript Support** - Full TypeScript definitions for better development experience  
+🔧 **Modular Architecture** - Tree-shakable imports for optimal bundle size  
+⚡ **High Performance** - Built with Svelte 5 for maximum performance  
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 📚 Documentation
+
+- **[Generated Component Reference](./docs/components/README.md)** - Source-derived API tables and a standalone Svelte example for every public component
+- **[API Naming Guide](./docs/NAMING.md)** - Naming conventions for props, callbacks, methods and types, with the 5.0.x → 5.1.0 rename table
+- **[AI Coding Prompts Index](./assets/ai-coding/README.md)** - Category guides and a full component API matrix, meant to be handed to an AI coding assistant
+- **[中文文档](./README_CN.md)** - Chinese documentation
+
+## Quick Start
+
+### 1. Import Styles
+
+```typescript
+// Import the main CSS file
+import '@ticatec/topside-elements/topside-elements.css';
+```
+
+### 2. Use Components
+
+```svelte
+<script lang="ts">
+  import Button from '@ticatec/topside-elements/Button';
+  import DataTable from '@ticatec/topside-elements/DataTable';
+  import type { DataColumn } from '@ticatec/topside-elements/DataTable';
+
+  let columns: DataColumn[] = [
+    { text: 'Name', field: 'name', width: 150 },
+    { text: 'Email', field: 'email', width: 200 }
+  ];
+
+  let data = [
+    { name: 'John Doe', email: 'john@example.com' },
+    { name: 'Jane Smith', email: 'jane@example.com' }
+  ];
+</script>
+
+<Button type="primary" onclick={() => console.log('Clicked!')}>
+  Click Me
+</Button>
+
+<DataTable {columns} list={data} />
+```
+
+## Component Categories
+
+### Layout Components
+- **App Layouts**: `SidebarLayout`, `HeaderLayout`, `ClassicLayout`, `ColumnsLayout`, `RowsLayout`
+- **Containers**: `Box`, `Card`, `Page`, `Accordion`
+- **Form Layouts**: `FlexForm`, `GridForm`, `FormField`
+- **Utilities**: `Split`, `Separator`
+
+### Data Display
+- **Tables**: `DataTable`, `ConciseDataTable`
+- **Lists**: `ListBox`, `TreeView`
+- **Navigation**: `Breadcrumbs`, `Tabs`, `NavigatorMenu`, `PageStack` | [Navigation Components Docs](./assets/ai-coding/05-navigation-and-general-guide.md)
+- **Indicators**: `ProgressBar`, `ProgressStepBar`, `Tag`
+
+### Form Controls
+- **Input**: `TextEditor`, `NumberEditor`, `MemoEditor`, `PasswordEditor` | [Form Editors Guide](./assets/ai-coding/01-form-editors-guide.md)
+- **Selection**: `OptionsSelect`, `OptionsMultiSelect`, `CascadeOptionsSelect`
+- **Date/Time**: `DatePicker`, `DateTimePicker`, `TimeEditor`
+- **Search/Filter**: `SearchBox`, `NumberRange`, `DateRange` - Advanced search and filtering components
+- **Others**: `CheckBox`, `RadioButton`, `Switch`, `ColorPicker`
+
+### Feedback Components
+- **Dialogs**: `Dialog`, `MessageBox`, `Drawer`
+- **Notifications**: `Toast`, `PopupHint`
+- **Overlays**: `FullScreenOverlay`
+
+### Advanced Components
+- **Editors**: `InlineCellEditor`, `PropertyEditor`, `PromptsTextEditor`
+- **File Upload**: `AttachmentEditor`, `ImageEditor`
+- **Data Transfer**: `Transfer`
+- **Search**: `SearchBox`, `CriteriaField`
+
+## Usage Examples
+
+### Data Table with Selection
+
+```svelte
+<script lang="ts">
+  import DataTable from '@ticatec/topside-elements/DataTable';
+  import type { DataColumn } from '@ticatec/topside-elements/DataTable';
+
+  let columns: DataColumn[] = [
+    {
+      field: 'name',
+      text: 'Name',
+      width: 200
+    },
+    {
+      field: 'email',
+      text: 'Email',
+      width: 250
+    },
+    {
+      field: 'status',
+      text: 'Status',
+      width: 120
+    }
+  ];
+  
+  let data = [
+    { id: 1, name: 'John Doe', email: 'john@example.com', status: 'Active' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com', status: 'Inactive' },
+    { id: 3, name: 'Bob Johnson', email: 'bob@example.com', status: 'Active' }
+  ];
+  
+  let selectedRows = [];
+</script>
+
+<DataTable {columns} list={data} bind:selectedRows />
+```
+
+### Dialog with Form
+
+```svelte
+<script lang="ts">
+  import Dialog from '@ticatec/topside-elements/Dialog';
+  import Button from '@ticatec/topside-elements/Button';
+  import TextEditor from '@ticatec/topside-elements/TextEditor';
+  import FormField from '@ticatec/topside-elements/FormField';
+
+  let showDialog = false;
+  let formData = { name: '', email: '' };
+
+  const actions = [
+    { label: 'Cancel', handler: () => { showDialog = false; } },
+    { label: 'Save', type: 'primary', handler: () => { showDialog = false; } }
+  ];
+</script>
+
+<Button onclick={() => showDialog = true}>Open Dialog</Button>
+
+<Dialog bind:visible={showDialog} title="Edit User" {actions}>
+  <FormField label="Name">
+    <TextEditor bind:value={formData.name} />
+  </FormField>
+
+  <FormField label="Email">
+    <TextEditor bind:value={formData.email} type="email" />
+  </FormField>
+</Dialog>
+```
+
+## Theme Customization
+
+The library uses CSS custom properties for theming. You can customize the appearance by overriding these variables:
+
+```css
+:root {
+  --topside-primary-color: #0061FF;
+  --topside-secondary-color: #22BDFF;
+  --topside-primary-text-color: #374151;
+  --topside-button-common-bg: #f0f0f0;
+  --topside-hover-item-background: #f7f7f7;
+  /* ... more variables */
+}
+```
+
+## Internationalization
+
+The library includes built-in internationalization support:
+
+The default language is English. Other languages are loaded dynamically at runtime, so adding a new language never requires a code change.
+
+Create a language resource json file in the static web directory, example: `/assets/uniface_zh-CN.json` (this is the complete key list):
+```json
+{
+  "uniface": {
+    "common": {
+      "btnClose": "关闭",
+      "btnCancel": "取消",
+      "btnConfirm": "确定",
+      "textMore": "加载更多",
+      "filterPlaceholder": "搜索...",
+      "noResultsText": "无匹配结果..."
+    },
+    "colorPicker": "选择颜色",
+    "calendar": {
+      "months": [
+        "一月", "二月", "三月", "四月", "五月", "六月", "七月", "八月", "九月", "十月", "十一月", "十二月"
+      ],
+      "monthsAbbr": [
+        "一月", "二月", "三月", "四月", "五月", "六月", "七月", "八月", "九月", "十月", "十一月", "十二月"
+      ],
+      "weekTitle": [
+        "周日", "周一", "周二", "周三", "周四", "周五", "周六"
+      ],
+      "weekTitleAbbr": [
+        "日", "一", "二", "三", "四", "五", "六"
+      ],
+      "confirmText": "确定"
+    },
+    "upload": {
+      "btnRetry": "重试",
+      "btnRemove": "删除",
+      "btnPickup": "选择文件"
+    },
+    "dataTable": {
+      "rowNo": "#",
+      "actions": "操作",
+      "emptyDataSet": "暂无数据",
+      "totalInfo": "共 <b>{{total}}</b> 条",
+      "rowsPerPage": "行/页"
+    },
+    "transfer": {
+      "selectIndicator": "已选择: {{selected}}/{{total}}"
+    }
+  }
+}
+```
+
+Load the resource file in `+page.svelte` or another startup page:
+
+```typescript
+import i18n, {i18nUtils} from "@ticatec/i18n";
+
+// 设置语言
+i18n.setLanguage('zh-CN'); // 或 'en'
+i18nUtils.loadResources('/assets/uniface.json'); // the language code will insert before .json => /assets/uniface_zh-CN.json
+```
+
+## Available Imports
+
+### Modular Imports
+```typescript
+// Individual component imports
+import Button from '@ticatec/topside-elements/Button';
+import DataTable from '@ticatec/topside-elements/DataTable';
+import SidebarLayout from '@ticatec/topside-elements/app-layout/SidebarLayout';
+import AttachmentEditor from '@ticatec/topside-elements/AttachmentEditor';
+import ImageEditor from '@ticatec/topside-elements/ImageEditor';
+import MemoEditor from '@ticatec/topside-elements/MemoEditor';
+
+// Utility imports
+import { utils } from '@ticatec/topside-elements/utils';
+import type { DataColumn } from '@ticatec/topside-elements/DataTable';
+```
+
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build the library
+npm run build
+
+# Run type checking
+npm run check
+```
+
+## Browser Support
+
+- Chrome ≥ 88
+- Firefox ≥ 85
+- Safari ≥ 14
+- Edge ≥ 88
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+## Author
+
+**Henry Feng** - [Ticatec](https://github.com/ticatec-auckland)
+
+## Documentation
+
+Component-by-category guides and a full props/events/snippets API matrix are available in [`assets/ai-coding/`](./assets/ai-coding/README.md):
+
+- [Form editors](./assets/ai-coding/01-form-editors-guide.md) - `TextEditor`, `NumberEditor`, `DatePicker`, `OptionsSelect`, `CheckBox`, `Switch`, and more
+- [Layouts and containers](./assets/ai-coding/02-layouts-and-containers-guide.md) - `FlexForm`, `GridForm`, `FormField`, `Page`, `ActionBar`, `SidebarLayout`, `ClassicLayout`
+- [Data display and tables](./assets/ai-coding/03-data-display-and-tables-guide.md) - `DataTable`, `ConciseDataTable`, `TreeView`, `Card`, `Accordion`, `ListBox`
+- [Overlays and feedback](./assets/ai-coding/04-overlays-and-feedback-guide.md) - `Dialog`, `CommonDialog`, `Drawer`, `Toast`, `MessageBox`, `Tooltip`, `ContextMenu`
+- [Navigation and general](./assets/ai-coding/05-navigation-and-general-guide.md) - `Tabs`, `Breadcrumbs`, `Pagination`, `Button`, `IconButton`, `Split`, `Tag`, `Transfer`
+- [Components API matrix](./assets/ai-coding/06-components-api-matrix.md) - full props/types/events/snippets reference for every core component
+
+You can also browse the demo components under `/src/routes/demo` for live, working examples.