@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/overlay/dialog/README_CN.md

@@ -0,0 +1,538 @@
+# Dialog 对话框
+
+基于 Svelte 5 构建的灵活模态对话框系统，提供 stack 式管理、Promise API、可拖拽对话框、可配置操作按钮和关闭确认。包含三个导出：`Dialog`（基础可定制对话框组件）、`CommonDialog`（简化确认/取消模式）和 `dialogManager`（全局 stack 控制器，自动挂载，返回 `Promise<ModalResult>`）。
+
+## 特性
+
+- **Stack 式管理**：控制器维护一个对话框栈，支持同时叠加多个对话框
+- **Promise API**：`dialogManager.show(component, params)` 返回 `Promise<ModalResult>`，调用方可 `await` 拿到关闭结果
+- **自动挂载**：首次调用 `show` 时控制器自动把 `DialogBoard` 挂载到 `document.body`，无需在 app 根手动放 `<DialogBoard/>`
+- **全局命令式 API**：`window.Dialog.show(component, params)` 也能用，方便从任意业务代码触发
+- **多种对话框类型**：`Dialog`、`CommonDialog`、`dialogManager`，适用于不同场景
+- **拖拽功能**：通过标题栏拖拽移动对话框
+- **操作按钮**：可配置按钮动作，返回 `true` 自动关闭
+- **关闭确认**：关闭前可选确认（适合有未保存更改的场景）
+- **ESC 关闭**：按 ESC 关闭对话框（自动让 picker 内部的 ESC 优先处理）
+- **生命周期钩子**：`onClose` 回调 + Promise resolve，通过 `ModalResult` 处理关闭结果
+- **可定制样式**：通过内联样式灵活调整外观和尺寸
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 引入
+
+```typescript
+import Dialog, { dialogManager, CommonDialog, ModalResult } from "@ticatec/uniface-element/Dialog";
+```
+
+## 设置
+
+**新项目无需任何设置**。控制器在你第一次调用 `dialogManager.show(...)` 时自动挂载到 `document.body`。
+
+> **旧项目兼容**：如果你之前在 app 根放了 `<DialogBoard/>`，可以保留也可以删除。多个 board 共存时只有第一个真正渲染 stack，不会重复显示对话框。
+
+## 两种使用模式
+
+### 模式一：命令式（推荐）
+
+把对话框内容封装成一个 Svelte 组件（内含 `<Dialog>` 壳 + 表单字段），调用 `dialogManager.show` 打开，`await` 拿到结果。
+
+**对话框组件**（接收 `user` 作为初始数据，`onSave` 作为保存回调）：
+
+```svelte
+<!-- UserDetailsDialog.svelte -->
+<script lang="ts">
+  import Dialog from "@ticatec/uniface-element/Dialog";
+  import FormContainer, {Row, CellField} from "@ticatec/uniface-element/FlexRowForm";
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  import RadioButton from "@ticatec/uniface-element/RadioButton";
+  import OptionsSelect from "@ticatec/uniface-element/OptionsSelect";
+  import DatePicker from "@ticatec/uniface-element/DatePicker";
+  import MemoEditor from "@ticatec/uniface-element/MemoEditor";
+  import type {ButtonAction} from "@ticatec/uniface-element/types";
+
+  let {user, onSave}: { user: any, onSave?: (data: any) => Promise<boolean> } = $props();
+
+  let name = $state(user?.name ?? "");
+  let gender = $state(user?.gender ?? "M");
+  let birthday = $state(user?.birthday);
+  let occupation = $state(user?.occupation ?? "dev");
+  let email = $state(user?.email ?? "");
+  let bio = $state(user?.bio ?? "");
+
+  const genderOptions = [
+    {code: "M", text: "男"},
+    {code: "F", text: "女"},
+    {code: "O", text: "其他"}
+  ];
+
+  const occupationOptions = [
+    {code: "dev", text: "工程师"},
+    {code: "design", text: "设计师"},
+    {code: "pm", text: "产品经理"}
+  ];
+
+  // action handler 返回 true，Dialog 自动关闭并以 MR_OK resolve
+  const actions: ButtonAction[] = [
+    {
+      label: "保存",
+      type: "primary",
+      handler: async () => {
+        const ok = await onSave?.({name, gender, birthday, occupation, email, bio});
+        return ok;
+      }
+    }
+  ];
+</script>
+
+<Dialog title="用户详情" {actions} width="500px">
+  <FormContainer>
+    <Row>
+      <CellField label="姓名" span={12} required>
+        <TextEditor bind:value={name} placeholder="请输入姓名"/>
+      </CellField>
+    </Row>
+
+    <Row>
+      <CellField label="性别" span={12}>
+        {#each genderOptions as opt}
+          <RadioButton label={opt.text} value={opt.code} bind:group={gender}/>
+        {/each}
+      </CellField>
+    </Row>
+
+    <Row>
+      <CellField label="生日" span={12}>
+        <DatePicker bind:value={birthday}/>
+      </CellField>
+    </Row>
+
+    <Row>
+      <CellField label="职业" span={12}>
+        <OptionsSelect bind:value={occupation} options={occupationOptions}/>
+      </CellField>
+    </Row>
+
+    <Row>
+      <CellField label="邮箱" span={12}>
+        <TextEditor bind:value={email} placeholder="example@domain.com"/>
+      </CellField>
+    </Row>
+
+    <Row>
+      <CellField label="简介" span={12}>
+        <MemoEditor bind:value={bio} rows={4}/>
+      </CellField>
+    </Row>
+  </FormContainer>
+</Dialog>
+```
+
+**调用方**（`await dialogManager.show` 拿到关闭结果）：
+
+```svelte
+<script lang="ts">
+  import {dialogManager, ModalResult} from "@ticatec/uniface-element/Dialog";
+  import UserDetailsDialog from "./UserDetailsDialog.svelte";
+
+  async function editUser(user: any) {
+    const result = await dialogManager.show(UserDetailsDialog, {
+      user,
+      onSave: async (data) => {
+        await api.updateUser(data);
+        return true;  // 返回 true 让 Dialog 的 action handler 也返回 true，触发关闭
+      }
+    });
+    if (result === ModalResult.MR_OK) {
+      await refreshList();
+    }
+  }
+</script>
+
+<button onclick={() => editUser(currentUser)}>编辑</button>
+```
+
+也可以用全局 `window.Dialog`（适合在非 Svelte 模块里调用，比如 service / store）：
+
+```typescript
+const result = await window.Dialog.show(MyDialog, { foo: "bar" });
+```
+
+> **`window.Dialog.showModal` 已废弃**：保留作为兼容别名，内部委托给 `show` 但丢弃 Promise。现有代码不用立刻改，但新代码请用 `show`。
+
+### 模式二：直接渲染
+
+如果你不想用 stack / Promise，只想在模板里条件渲染一个对话框，也可以直接用 `<Dialog>`：
+
+```svelte
+<script>
+  import Dialog, { ModalResult } from "@ticatec/uniface-element/Dialog";
+
+  let showDialog = $state(false);
+
+  function handleClose(result) {
+    console.log("对话框关闭，结果：", result);
+    showDialog = false;
+  }
+</script>
+
+{#if showDialog}
+  <Dialog
+    title="我的对话框"
+    onClose={handleClose}
+    width="500px"
+    height="300px"
+  >
+    <p>对话框内容...</p>
+  </Dialog>
+{/if}
+```
+
+直接渲染模式下没有 `dialogId` context，`close()` 会自己调 `onClose`。
+
+## 组件概览
+
+### Dialog
+
+基础对话框组件，支持完整的自定义选项。两种模式下都能用。
+
+### CommonDialog
+
+带内置确认按钮的简化封装，适合"确认/取消"场景。
+
+### dialogManager
+
+全局 stack 控制器。维护对话框栈，提供 `show` / `resolveWith` API。
+
+## Dialog 组件
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `title` | `string` | `''` | 标题栏文字 |
+| `width` | `string` | `'unset'` | 对话框宽度（CSS 值） |
+| `height` | `string` | `'unset'` | 对话框高度（CSS 值） |
+| `actions` | `ButtonActions \| null` | `null` | 操作按钮数组，`null` 条目作为分隔符 |
+| `closeConfirm` | `DialogCloseConfirm \| null` | `null` | 关闭确认函数，当结果为 `MR_CANCEL` 或 `MR_CLOSE` 时调用，应返回 `Promise<boolean>` |
+| `content$style` | `string` | `''` | 内容区域自定义内联样式 |
+| `hideClose` | `boolean` | `false` | 为 `true` 时隐藏标题栏的关闭 X 图标 |
+| `closeAction` | `ButtonAction \| null` | `null` | 覆盖默认关闭按钮（label/type 等），handler 始终绑定到内部 close |
+| `onClose` | `OnClose \| null` | `null` | 关闭回调，接收 `ModalResult`（参见[模态结果](#模态结果)） |
+| `dialog$style` | `string` | `''` | 对话框容器自定义内联样式 |
+
+### 方法
+
+| 方法 | 描述 |
+|------|------|
+| `close(result: ModalResult)` | 用 `bind:this` 拿到实例后调用，以指定结果关闭对话框 |
+
+### 事件
+
+| 事件 | 说明 |
+|------|------|
+| `onClose` | 关闭时触发。接收 `ModalResult.MR_OK` / `MR_CANCEL` / `MR_CLOSE` |
+
+## CommonDialog 组件
+
+简化封装，自动提供"确认"按钮。两种模式下都能用。
+
+### 基本用法
+
+```svelte
+<script>
+  import { CommonDialog } from "@ticatec/uniface-element/Dialog";
+
+  let showDialog = $state(false);
+
+  async function handleConfirm() {
+    console.log("已确认！");
+    return true; // 返回 true 自动关闭
+  }
+
+  function handleClose(result) {
+    console.log("结果：", result);
+    showDialog = false;
+  }
+</script>
+
+{#if showDialog}
+  <CommonDialog
+    title="确认操作"
+    confirmHandler={handleConfirm}
+    onClose={handleClose}
+    width="400px"
+  >
+    <p>确定要继续吗？</p>
+  </CommonDialog>
+{/if}
+```
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `title` | `string` | `''` | 对话框标题 |
+| `width` | `string` | `'unset'` | 对话框宽度 |
+| `height` | `string` | `'unset'` | 对话框高度 |
+| `closeConfirm` | `DialogCloseConfirm \| null` | `null` | 关闭确认函数 |
+| `content$style` | `string` | `''` | 内容区域样式 |
+| `enableConfirm` | `boolean` | `true` | 启用/禁用确认按钮 |
+| `confirmHandler` | `(() => Promise<any>) \| null` | `null` | 确认按钮处理函数 |
+| `confirmText` | `string \| null` | `null` | 自定义确认按钮文本（默认用 i18n "确认"） |
+| `onClose` | `OnClose \| null` | `null` | 关闭回调，接收 `ModalResult` |
+
+## 全局 API
+
+### `dialogManager.show(component, params): Promise<ModalResult>`
+
+打开一个对话框，把 `params` 作为 props 传给 `component`。Promise 在对话框关闭时 resolve，值是用户的关闭结果。
+
+```typescript
+import { dialogManager, ModalResult } from "@ticatec/uniface-element/Dialog";
+
+const result = await dialogManager.show(MyDialog, {
+  title: "示例",
+  onClose: (r) => console.log("closed:", r)  // 也可在这里拿结果
+});
+```
+
+### `window.Dialog.show(component, params): Promise<ModalResult>`
+
+同上，但挂在 `window` 上，方便非 Svelte 模块（service / store / 工具函数）调用。第一次调用前 `window.Dialog` 已在模块加载时设置好。
+
+### `window.Dialog.showModal(component, params): void`
+
+**已废弃**。兼容旧调用，丢弃 Promise 返回值。新代码请用 `show`。
+
+## 操作按钮
+
+### 按钮配置
+
+```typescript
+type ButtonAction = {
+  label: string;
+  type?: "primary" | "secondary" | "danger";
+  disabled?: boolean;
+  handler?: (event: MouseEvent) => Promise<boolean> | boolean;
+};
+
+type ButtonActions = (ButtonAction | null)[];
+```
+
+返回 `true` 的 action 自动关闭对话框并以 `ModalResult.MR_OK` resolve。用 `null` 条目在按钮行中插入分隔符。
+
+### 示例
+
+```svelte
+<script>
+  const actions = [
+    {
+      label: "删除",
+      type: "danger",
+      handler: async () => {
+        const ok = await confirmDelete();
+        if (ok) {
+          await deleteItem();
+          return true; // 关闭
+        }
+        return false; // 保持打开
+      }
+    },
+    null, // 分隔符
+    {
+      label: "保存",
+      type: "primary",
+      disabled: !isValid,
+      handler: async () => {
+        await saveData();
+        return true;
+      }
+    }
+  ];
+</script>
+```
+
+## 关闭确认
+
+为有未保存更改的场景添加关闭前确认（点 X / ESC / Cancel 按钮时触发）：
+
+```svelte
+<script>
+  import { ModalResult } from "@ticatec/uniface-element/Dialog";
+  import messageBox from "@ticatec/uniface-element/MessageBox";
+
+  let originalData = JSON.stringify(data);
+
+  const closeConfirm = async () => {
+    const hasChanges = JSON.stringify(data) !== originalData;
+    if (hasChanges) {
+      return await messageBox.showConfirm("有未保存的更改，确定要关闭吗？", { title: "确认关闭" })
+        === ModalResult.MR_OK;
+    }
+    return true;
+  };
+</script>
+
+<Dialog {closeConfirm}>
+  <!-- 内容 -->
+</Dialog>
+```
+
+## 模态结果
+
+`ModalResult` 与 `MessageBox` 共用同一份枚举：
+
+```typescript
+enum ModalResult {
+  MR_OK = 1,     // 用户确认（点了返回 true 的 action）
+  MR_CANCEL = 2, // 用户取消（点了 Cancel / X / ESC）
+  MR_CLOSE = 3   // 程序化关闭（目前未使用，预留给"区分 X 和 Cancel"的场景）
+}
+```
+
+### 处理结果
+
+```svelte
+<script>
+  import { ModalResult } from "@ticatec/uniface-element/Dialog";
+
+  function handleDialogClose(result) {
+    if (result === ModalResult.MR_OK) {
+      console.log("用户确认");
+    } else {
+      console.log("用户取消");
+    }
+  }
+</script>
+```
+
+## Stack 行为
+
+控制器内部维护一个 stack，每次 `show` 都会把新 entry 推入栈：
+
+```typescript
+// 同时存在两个对话框 —— 后开的盖在前面
+await dialogManager.show(Dialog, { title: "底层" });
+await dialogManager.show(Dialog, { title: "顶层" });
+```
+
+每个 entry 持有自己的 Promise resolver，互不影响。原生 `<dialog>` 的 top-layer 渲染保证栈顶对话框永远在最上层，无需手动管理 z-index。关闭栈中某个对话框时，Promise 用对应结果 resolve，控制器自动出栈。
+
+## 对话框大小和定位
+
+### 响应式大小
+
+```svelte
+<!-- 固定大小 -->
+<Dialog width="500px" height="400px">
+
+<!-- 响应式大小 -->
+<Dialog width="90vw" height="80vh">
+
+<!-- 自动大小，带最大约束 -->
+<Dialog
+  width="min(800px, 90vw)"
+  height="min(600px, 80vh)"
+>
+```
+
+### 自定义样式
+
+```svelte
+<Dialog
+  dialog$style="border-radius: 12px; box-shadow: 0 20px 40px rgba(0,0,0,0.3);"
+  content$style="padding: 2rem; background: #f9f9f9;"
+>
+```
+
+## 验证与错误处理
+
+参考[模式一](#模式一命令式推荐)的 `UserDetailsDialog`，只需在 action handler 里加验证逻辑：
+
+```svelte
+<script lang="ts">
+  // ... 字段定义同模式一 ...
+
+  let errors = $state<Record<string, string>>({});
+
+  function validate(): boolean {
+    errors = {};
+    if (!name) errors.name = "姓名必填";
+    if (!email) errors.email = "邮箱必填";
+    else if (!email.includes("@")) errors.email = "邮箱格式无效";
+    return Object.keys(errors).length === 0;
+  }
+
+  const actions: ButtonAction[] = [
+    {
+      label: "保存",
+      type: "primary",
+      handler: async () => {
+        if (!validate()) return false;  // 验证失败 → 保持打开
+        try {
+          await onSave?.({name, gender, birthday, occupation, email, bio});
+          return true;                   // 成功 → 关闭并 resolve MR_OK
+        } catch (e) {
+          console.error("保存失败：", e);
+          return false;
+        }
+      }
+    }
+  ];
+</script>
+
+<!-- 字段上传入 error -->
+<CellField label="姓名" span={12} required>
+  <TextEditor bind:value={name} placeholder="请输入姓名" error={errors.name}/>
+</CellField>
+```
+
+要点：
+- handler 返回 `false` → 对话框保持打开
+- handler 返回 `true`（或省略 return） → 关闭并 `resolve(MR_OK)`
+- handler 抛异常 → 自己 catch，否则 Promise reject 影响调用方
+
+## 最佳实践
+
+1. **优先用命令式 API（`dialogManager.show`）**：返回 Promise，方便链式处理结果，也方便 service / store 调用。
+2. **无需手动挂载 `DialogBoard`**：控制器自动挂载。旧项目里已有的 `<DialogBoard/>` 可以保留也可以删。
+3. **action handler 返回 `false` 保持对话框打开**（比如验证失败时）。
+4. **有未保存更改时用 `closeConfirm`** —— 弹一个 MessageBox 确认是否离开。
+5. **根据场景选择尺寸** —— 简单对话框 400–600px，表单对话框 700–900px，移动端用响应式。
+6. **stack 是支持的，但别滥用**：同时叠加多个对话框会让用户困惑，需要时再用。
+
+## TypeScript 支持
+
+`window.Dialog` 的类型已通过包内 `declare global` 注入，通常无需额外配置。如果自动补全不工作，手动添加：
+
+```typescript
+import type { IDialog } from "@ticatec/uniface-element/Dialog";
+
+declare global {
+  interface Window {
+    Dialog: IDialog;
+  }
+}
+```
+
+## 迁移指南（从旧版本）
+
+| 旧 API | 新 API | 备注 |
+|---|---|---|
+| `<DialogBoard/>` 在 app 根 | 无需 | 控制器自动挂载，旧代码可保留 |
+| `window.Dialog.showModal(Component, params)` | `window.Dialog.show(Component, params)` 或 `dialogManager.show(...)` | `showModal` 仍可用（兼容别名），但丢弃 Promise |
+| `ModalResult.Ok` / `ModalResult.Cancel` | `ModalResult.MR_OK` / `ModalResult.MR_CANCEL` | 枚举值已与 MessageBox 统一 |
+| `onClose(result)` 回调 | `onClose(result)` + `await dialogManager.show(...)` | 两者都支持，Promise 是新方式 |
+
+## 相关组件
+
+- [MessageBox](../message-box/README_CN.md) — 全局模态框，用于确认和需要用户知晓的消息
+- [Toast](../toast/README_CN.md) — 非阻塞的临时通知
+- [Indicator](../indicator/README_CN.md) — 全屏加载指示器
+- [Drawer](../drawer/README_CN.md) — 侧边滑出面板
+- [ContextMenu](../context-menu/README_CN.md) — 带键盘导航的右键菜单
+- [Tooltip](../tooltip/README_CN.md) — 悬停式上下文提示

package/dist/overlay/dialog/index.d.ts

@@ -0,0 +1,14 @@
+import Dialog from "./Dialog.svelte";
+import dialogManager from "./DialogManager.svelte";
+import type IDialog from "./IDialog";
+import { ModalResult, type OnClose } from "./IDialog";
+import type { DialogCloseConfirm } from "./DialogCloseConfirm";
+import CommonDialog from "./CommonDialog.svelte";
+import DialogBoard from "./DialogBoard.svelte";
+declare global {
+    interface Window {
+        Dialog: IDialog;
+    }
+}
+export default Dialog;
+export { dialogManager, ModalResult, type OnClose, type IDialog, type DialogCloseConfirm, CommonDialog, DialogBoard };

package/dist/overlay/dialog/index.js

@@ -0,0 +1,7 @@
+import Dialog from "./Dialog.svelte";
+import dialogManager from "./DialogManager.svelte";
+import { ModalResult } from "./IDialog";
+import CommonDialog from "./CommonDialog.svelte";
+import DialogBoard from "./DialogBoard.svelte";
+export default Dialog;
+export { dialogManager, ModalResult, CommonDialog, DialogBoard };

package/dist/overlay/drawer/Drawer.svelte

@@ -0,0 +1,89 @@
+<script lang="ts">
+    import {fly} from "svelte/transition";
+    import type { Snippet } from "svelte";
+
+    interface Props {
+        theme?: string;
+        visible?: boolean;
+        width?: number;
+        position?: 'left' | 'right';
+        children?: Snippet;
+    }
+
+    let {
+        theme,
+        visible = $bindable(false),
+        width = 300,
+        position = 'left',
+        children
+    }: Props = $props();
+
+    let hidden = $state(true);
+
+    $effect(() => {
+        if (visible) {
+            hidden = false;
+        }
+    });
+
+    let xPos = $derived(position == 'left' ? `${-width}` : '100%');
+
+    const handleBackdropClick = () => {
+        visible = false;
+    };
+
+    const handleDrawerClick = (e: MouseEvent) => {
+        e.stopPropagation();
+    };
+</script>
+
+<div class="uniface-drawer" aria-hidden="true" data-theme={theme} style="display: {hidden ? 'none' : 'block'}" onclick={handleBackdropClick}>
+    {#if visible}
+        <div class={position} style="width: {width}px" transition:fly={{ x: xPos, duration: 1000, opacity: 0.5 }} aria-hidden="true"
+             onoutroend={()=>{hidden = !visible}} onclick={handleDrawerClick}>
+            <div>
+            {#if children}
+                {@render children()}
+            {/if}
+            </div>
+        </div>
+    {/if}
+</div>
+
+<style>
+    .uniface-drawer {
+        position: fixed;
+        top: 0;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        background-color: transparent;
+        z-index: 99;
+    }
+
+    .uniface-drawer > div {
+        position: absolute;
+        height: 100%;
+        background-color: var(--uniface-drawer-color-surface);
+        color: var(--uniface-color-primary);
+    }
+
+    .uniface-drawer > div > div {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        overflow: auto;
+    }
+
+    .uniface-drawer > div.left {
+        left: 0;
+        border-right: 1px solid var(--uniface-color-border-secondary);
+        box-shadow: var(--uniface-drawer-left-shadow);
+    }
+
+    .uniface-drawer > div.right {
+        right: 0;
+        border-left: 1px solid var(--uniface-color-border-secondary);
+        box-shadow: var(--uniface-drawer-right-shadow);
+    }
+</style>

package/dist/overlay/drawer/Drawer.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+interface Props {
+    theme?: string;
+    visible?: boolean;
+    width?: number;
+    position?: 'left' | 'right';
+    children?: Snippet;
+}
+declare const Drawer: import("svelte").Component<Props, {}, "visible">;
+type Drawer = ReturnType<typeof Drawer>;
+export default Drawer;