@ticatec/topside-elements 1.0.0

package/README_CN.md

@@ -0,0 +1,372 @@
+# 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)
+
+基于 Svelte 5 构建的全面企业级 UI 组件库，专为现代化 Web 应用程序设计。
+
+[English Documentation](./README.md)
+
+## 特性
+
+✨ **企业级组件** - 为商业应用提供完整的组件集合  
+🎨 **主题系统** - 基于 CSS 变量的主题化，可自定义设计令牌  
+📱 **响应式设计** - 移动优先的响应式组件  
+🌍 **国际化支持** - 内置中英文国际化资源  
+🎯 **TypeScript 支持** - 完整的 TypeScript 类型定义，提供更好的开发体验  
+🔧 **模块化架构** - 支持按需导入，优化打包体积  
+⚡ **高性能** - 基于 Svelte 5 构建，性能卓越  
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 组件文档
+
+- **[自动生成的组件参考](./docs/components/README.md)**：覆盖全部公开组件的源码派生属性表和独立 Svelte 示例
+- **[API 命名规范](./docs/NAMING_CN.md)**：属性、回调、方法、类型的命名约定，以及 5.0.x → 5.1.0 的新旧对照表
+
+## 快速开始
+
+### 1. 导入样式
+
+```typescript
+// 导入主样式文件
+import '@ticatec/topside-elements/topside-elements.css';
+```
+
+### 2. 使用组件
+
+```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[] = [
+    { field: 'name', text: '姓名', width: 150 },
+    { field: 'email', text: '邮箱', width: 200 }
+  ];
+  
+  let data = [
+    { name: '张三', email: 'zhangsan@example.com' },
+    { name: '李四', email: 'lisi@example.com' }
+  ];
+</script>
+
+<Button type="primary" onclick={() => console.log('点击了!')}>
+  点击我
+</Button>
+
+<DataTable {columns} list={data} />
+```
+
+## 组件分类
+
+### 布局组件
+- **应用布局**: `SidebarLayout`、`HeaderLayout`、`ClassicLayout`、`ColumnsLayout`、`RowsLayout`
+- **容器组件**: `Box`、`Card`、`Page`、`Accordion`
+- **表单布局**: `FlexForm`、`GridForm`、`FormField`
+- **工具组件**: `Split`、`Separator`
+
+### 数据展示
+- **表格组件**: `DataTable`、`ConciseDataTable`
+- **列表组件**: `ListBox`、`TreeView`
+- **导航组件**: `Breadcrumbs`、`Tabs`、`NavigatorMenu`、`PageStack`
+- **指示器**: `ProgressBar`、`ProgressStepBar`、`Tag`
+
+### 表单控件
+- **输入组件**: `TextEditor`、`NumberEditor`、`MemoEditor`、`PasswordEditor`
+- **选择组件**: `OptionsSelect`、`OptionsMultiSelect`、`CascadeOptionsSelect`
+- **日期时间**: `DatePicker`、`DateTimePicker`、`TimeEditor`
+- **其他控件**: `CheckBox`、`RadioButton`、`Switch`、`ColorPicker`
+
+### 反馈组件
+- **对话框**: `Dialog`、`MessageBox`、`Drawer`
+- **消息通知**: `Toast`、`PopupHint`
+- **遮罩层**: `FullScreenOverlay`
+
+### 高级组件
+- **编辑器**: `InlineCellEditor`、`PropertyEditor`、`PromptsTextEditor`
+- **文件上传**: `AttachmentEditor`、`ImageEditor`
+- **数据传输**: `Transfer`
+- **搜索组件**: `SearchBox`、`CriteriaField`
+
+## 页面 Overlay 控制器
+
+Overlay 控制器（`indicator`、`toast`、`messageBox`）在首次使用时会自动挂载至 `document.body`，应用内任何位置的代码均可直接导入并使用，无需在根节点手动挂载 Board 组件。
+
+```svelte
+<script lang="ts">
+  import indicator from "@ticatec/topside-elements/Indicator";
+  import toast from "@ticatec/topside-elements/Toast";
+  import messageBox, { ModalResult } from "@ticatec/topside-elements/MessageBox";
+</script>
+```
+
+### 异步操作指示器 `Indicator`
+
+用于异步操作时遮罩页面并显示操作信息，避免用户重复或异常操作：
+
+```typescript
+import indicator from "@ticatec/topside-elements/Indicator";
+
+try {
+  indicator.show('正在加载数据...');
+  // 异步调用 await service.search();
+} finally {
+  indicator.hide();
+}
+```
+
+### 弹出消息 `Toast`
+
+用于显示操作结果和轻量提示信息：
+
+```typescript
+import toast from "@ticatec/topside-elements/Toast";
+
+// 显示错误消息（持续2秒）
+toast.error("无法删除活跃用户", 2);
+
+// 显示成功消息
+toast.success("操作成功");
+
+// 显示信息提示
+toast.info("这是一条提示信息");
+```
+
+### 消息提示框 `MessageBox`
+
+用于确认操作和模态信息提示：
+
+```typescript
+import messageBox, { ModalResult } from "@ticatec/topside-elements/MessageBox";
+
+const deleteConfirm = async (user: any) => {
+  const result = await messageBox.showConfirm(`确定要删除用户[${user.name}]吗？`, {
+    title: "删除确认",
+    type: "warning"
+  });
+  if (result === ModalResult.MR_OK) {
+    // 执行删除操作
+    toast.success("删除成功");
+  }
+}
+
+// 显示信息提示
+await messageBox.showInfo("操作完成", { title: "提示" });
+```
+
+## 使用示例
+
+### 带行选择的数据表格
+
+```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: '姓名',
+      width: 200
+    },
+    {
+      field: 'email',
+      text: '邮箱',
+      width: 250
+    },
+    {
+      field: 'status',
+      text: '状态',
+      width: 120
+    }
+  ];
+  
+  let data = [
+    { id: 1, name: '张三', email: 'zhangsan@example.com', status: '活跃' },
+    { id: 2, name: '李四', email: 'lisi@example.com', status: '非活跃' },
+    { id: 3, name: '王五', email: 'wangwu@example.com', status: '活跃' }
+  ];
+  
+  let selectedRows = [];
+</script>
+
+<DataTable {columns} list={data} bind:selectedRows />
+```
+
+### 表单对话框
+
+```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: '取消', handler: () => { showDialog = false; } },
+    { label: '保存', type: 'primary', handler: () => { showDialog = false; } }
+  ];
+</script>
+
+<Button onclick={() => showDialog = true}>打开对话框</Button>
+
+<Dialog bind:visible={showDialog} title="编辑用户" {actions}>
+  <FormField label="姓名">
+    <TextEditor bind:value={formData.name} />
+  </FormField>
+
+  <FormField label="邮箱">
+    <TextEditor bind:value={formData.email} type="email" />
+  </FormField>
+</Dialog>
+```
+
+## 布局组件详细介绍
+
+## 文档
+
+按类别划分的组件指南以及完整的属性/事件/Snippet API 矩阵，位于 [`assets/ai-coding/`](./assets/ai-coding/README.md)：
+
+- [表单编辑器](./assets/ai-coding/01-form-editors-guide.md) - `TextEditor`、`NumberEditor`、`DatePicker`、`OptionsSelect`、`CheckBox`、`Switch` 等
+- [布局与容器](./assets/ai-coding/02-layouts-and-containers-guide.md) - `FlexForm`、`GridForm`、`FormField`、`Page`、`ActionBar`、`SidebarLayout`、`ClassicLayout`
+- [数据展示与表格](./assets/ai-coding/03-data-display-and-tables-guide.md) - `DataTable`、`ConciseDataTable`、`TreeView`、`Card`、`Accordion`、`ListBox`
+- [弹层与反馈](./assets/ai-coding/04-overlays-and-feedback-guide.md) - `Dialog`、`CommonDialog`、`Drawer`、`Toast`、`MessageBox`、`Tooltip`、`ContextMenu`
+- [导航与通用组件](./assets/ai-coding/05-navigation-and-general-guide.md) - `Tabs`、`Breadcrumbs`、`Pagination`、`Button`、`IconButton`、`Split`、`Tag`、`Transfer`
+- [组件 API 矩阵](./assets/ai-coding/06-components-api-matrix.md) - 所有核心组件的完整 Props/Types/Events/Snippets 参考
+
+也可以查看 `/src/routes/demo` 目录下的示例组件，获取可运行的真实用法。
+
+## 主题定制
+
+组件库使用 CSS 自定义属性进行主题化。你可以通过覆盖这些变量来自定义外观：
+
+```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;
+  /* ... 更多变量 */
+}
+```
+
+## 国际化
+
+组件库内置国际化支持:
+
+默认语言为英文。其他语言在运行时动态加载,未来新增语言无需修改代码。
+
+在静态资源目录下创建语言资源 json 文件,例如 `/assets/uniface_zh-CN.json`(以下为完整键列表):
+```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}}"
+    }
+  }
+}
+```
+
+在 `+page.svelte` 或其他启动页加载资源文件:
+
+```typescript
+import i18n, {i18nUtils} from "@ticatec/i18n";
+
+// 设置语言
+i18n.setLanguage('zh-CN'); // 或 'en'
+i18nUtils.loadResources('/assets/uniface.json'); // 语言代码会插入到 .json 之前 => /assets/uniface_zh-CN.json
+```
+
+## 可用导入
+
+### 模块化导入
+```typescript
+// 单个组件导入
+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';
+
+// 工具导入
+import { utils } from '@ticatec/topside-elements/utils';
+import type { DataColumn } from '@ticatec/topside-elements/DataTable';
+```
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器
+npm run dev
+
+# 构建组件库
+npm run build
+
+# 运行类型检查
+npm run check
+```
+
+## 浏览器支持
+
+- Chrome ≥ 88
+- Firefox ≥ 85
+- Safari ≥ 14
+- Edge ≥ 88
+
+## 许可证
+
+MIT 许可证 - 查看 [LICENSE](./LICENSE) 文件了解详细信息。
+
+## 作者
+
+**Henry Feng** - [Ticatec](https://github.com/ticatec-auckland)

package/dist/app_layout/ClassicLayout.svelte

@@ -0,0 +1,140 @@
+<script lang="ts">
+    import type { Snippet } from 'svelte';
+    import Split from "../general/split";
+
+    interface Props {
+        headerHeight?: string;
+        sidebarWidth?: string;
+        statusHeight?: string;
+        rightBarWidth?: string;
+        sidebarResize?: boolean;
+        sidebarMaxWidth?: string | null;
+        sidebarMinWidth?: string | null;
+        rightBarResize?: boolean;
+        rightBarMaxWidth?: string | null;
+        rightBarMinWidth?: string | null;
+        header?: Snippet;
+        sidebar?: Snippet;
+        children?: Snippet;
+        rightSidebar?: Snippet;
+        bottom?: Snippet;
+    }
+
+    let {
+        headerHeight = "48px",
+        sidebarWidth = '300px',
+        statusHeight = "22px",
+        rightBarWidth = '240px',
+        sidebarResize = false,
+        sidebarMaxWidth = null,
+        sidebarMinWidth = null,
+        rightBarResize = false,
+        rightBarMaxWidth = null,
+        rightBarMinWidth = null,
+        header,
+        sidebar,
+        children,
+        rightSidebar,
+        bottom
+    }: Props = $props();
+
+    let sidebarPanel = $state<HTMLElement>();
+    let rightBarPanel = $state<HTMLElement>();
+    let maxWidth = $derived(sidebarResize && sidebarMaxWidth ? `max-width: ${sidebarMaxWidth};` : '');
+    let minWidth = $derived(sidebarResize && sidebarMinWidth ? `min-width: ${sidebarMinWidth};` : '');
+    let rightMaxWidth = $derived(rightBarResize && rightBarMaxWidth ? `max-width: ${rightBarMaxWidth};` : '');
+    let rightMinWidth = $derived(rightBarResize && rightBarMinWidth ? `min-width: ${rightBarMinWidth};` : '');
+</script>
+
+<div class="topside-classic-layout">
+    {#if header}
+        <div class="header-area" style="height: {headerHeight}">
+            {@render header()}
+        </div>
+    {/if}
+    <div class="middle-area">
+        {#if sidebar}
+            <div bind:this={sidebarPanel} class="sidebar" style="width: {sidebarWidth}; {maxWidth} {minWidth}">
+                {#if sidebar}
+                    {@render sidebar()}
+                {/if}
+            </div>
+        {/if}
+        {#if sidebarResize}
+            <Split direction="vertical" bindingPanel={sidebarPanel}/>
+        {/if}
+        <div class="content-area">
+            {#if children}
+                {@render children()}
+            {/if}
+        </div>
+        {#if rightSidebar}
+            {#if rightBarResize}
+                <Split direction="vertical" bindingPanel={rightBarPanel} reverse/>
+            {/if}
+            <div bind:this={rightBarPanel} class="right-sidebar" style="width: {rightBarWidth}; {rightMinWidth} {rightMaxWidth}">
+                {#if rightSidebar}
+                    {@render rightSidebar()}
+                {/if}
+            </div>
+        {/if}
+    </div>
+    {#if bottom}
+        <div class="bottom-area" style="height: {statusHeight}">
+            {@render bottom()}
+        </div>
+    {/if}
+</div>
+
+<style>
+    .topside-classic-layout {
+        width: 100%;
+        height: 100%;
+        box-sizing: border-box;
+        display: flex;
+        flex-direction: column;
+        position: relative;
+    }
+
+    .header-area {
+        flex: 0 0 auto;
+        position: relative;
+        width: 100%;
+        overflow: hidden;
+    }
+
+    .middle-area {
+        flex: 1 1 auto;
+        overflow: hidden;
+        display: flex;
+        flex-direction: row;
+        position: relative;
+    }
+
+    .sidebar {
+        flex: 0 0 auto;
+        overflow: auto;
+        width: 100%;
+        border-right: 1px solid var(--topside-color-border-secondary);
+    }
+
+    .content-area {
+        flex: 1 1 auto;
+        overflow: auto;
+    }
+
+    .right-sidebar {
+        flex: 0 0 auto;
+        overflow: auto;
+        width: 100%;
+        border-left: 1px solid var(--topside-color-border-secondary);
+    }
+
+    .bottom-area {
+        flex: 0 0 auto;
+        position: relative;
+        width: 100%;
+        overflow: hidden;
+        border-top: 1px solid var(--topside-color-border-secondary);
+    }
+</style>

package/dist/app_layout/ClassicLayout.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    headerHeight?: string;
+    sidebarWidth?: string;
+    statusHeight?: string;
+    rightBarWidth?: string;
+    sidebarResize?: boolean;
+    sidebarMaxWidth?: string | null;
+    sidebarMinWidth?: string | null;
+    rightBarResize?: boolean;
+    rightBarMaxWidth?: string | null;
+    rightBarMinWidth?: string | null;
+    header?: Snippet;
+    sidebar?: Snippet;
+    children?: Snippet;
+    rightSidebar?: Snippet;
+    bottom?: Snippet;
+}
+declare const ClassicLayout: import("svelte").Component<Props, {}, "">;
+type ClassicLayout = ReturnType<typeof ClassicLayout>;
+export default ClassicLayout;

package/dist/app_layout/ColumnsLayout.svelte

@@ -0,0 +1,95 @@
+<script lang="ts">
+    import type { Snippet } from 'svelte';
+    import Split from "../general/split";
+
+    interface Props {
+        width?: string;
+        height?: string;
+        leftWidth?: string | null;
+        rightWidth?: string | null;
+        /** 左栏最小宽度（CSS 长度） */
+        leftMinWidth?: string | null;
+        /** 左栏最大宽度（CSS 长度） */
+        leftMaxWidth?: string | null;
+        /** 右栏最小宽度（CSS 长度） */
+        rightMinWidth?: string | null;
+        /** 右栏最大宽度（CSS 长度） */
+        rightMaxWidth?: string | null;
+        leftResize?: boolean;
+        rightResize?: boolean;
+        left?: Snippet;
+        children?: Snippet;
+        right?: Snippet;
+    }
+
+    let {
+        width = '100%',
+        height = '100%',
+        leftWidth = null,
+        rightWidth = null,
+        leftMinWidth = null,
+        leftMaxWidth = null,
+        rightMinWidth = null,
+        rightMaxWidth = null,
+        leftResize = false,
+        rightResize = false,
+        left,
+        children,
+        right
+    }: Props = $props();
+
+    let leftPanel = $state<HTMLElement>();
+    let rightPanel = $state<HTMLElement>();
+
+    let colWidth = $derived(right ? '25%' : '50%');
+
+    const generateStyle = (attr: string, v: string | null): string => {
+        return v ? `${attr}: ${v};` : ''
+    }
+
+    let leftStyle = $derived(`${generateStyle('min-width', leftMinWidth)} ${generateStyle('max-width', leftMaxWidth)} ${generateStyle('width', leftWidth ?? colWidth)}`);
+    let rightStyle = $derived(`${generateStyle('min-width', rightMinWidth)} ${generateStyle('max-width', rightMaxWidth)} ${generateStyle('width', rightWidth ?? colWidth)}`);
+</script>
+
+<div class="topside-columns-layout" style="width: {width}; height: {height}">
+    <div bind:this={leftPanel} class="left-panel" style={leftStyle}>
+        {#if left}
+            {@render left()}
+        {/if}
+    </div>
+    {#if leftResize}
+        <Split bindingPanel={leftPanel}/>
+    {/if}
+    <div class="center-panel">
+        {#if children}
+            {@render children()}
+        {/if}
+    </div>
+    {#if right}
+        {#if rightResize}
+            <Split bindingPanel={rightPanel} reverse/>
+        {/if}
+        <div bind:this={rightPanel} class="right-panel" style={rightStyle}>
+            {@render right()}
+        </div>
+    {/if}
+</div>
+
+<style>
+    .topside-columns-layout {
+        display: flex;
+        flex-direction: row;
+        flex-wrap: nowrap;
+    }
+
+    .left-panel,
+    .right-panel {
+        flex: 0 0 auto;
+        overflow: auto;
+    }
+
+    .center-panel {
+        flex: 1 1 auto;
+        overflow: auto;
+    }
+</style>

package/dist/app_layout/ColumnsLayout.svelte.d.ts

@@ -0,0 +1,23 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    width?: string;
+    height?: string;
+    leftWidth?: string | null;
+    rightWidth?: string | null;
+    /** 左栏最小宽度（CSS 长度） */
+    leftMinWidth?: string | null;
+    /** 左栏最大宽度（CSS 长度） */
+    leftMaxWidth?: string | null;
+    /** 右栏最小宽度（CSS 长度） */
+    rightMinWidth?: string | null;
+    /** 右栏最大宽度（CSS 长度） */
+    rightMaxWidth?: string | null;
+    leftResize?: boolean;
+    rightResize?: boolean;
+    left?: Snippet;
+    children?: Snippet;
+    right?: Snippet;
+}
+declare const ColumnsLayout: import("svelte").Component<Props, {}, "">;
+type ColumnsLayout = ReturnType<typeof ColumnsLayout>;
+export default ColumnsLayout;