@ticatec/topside-elements 1.0.0

package/dist/overlay/message-box/README.md

@@ -0,0 +1,92 @@
+# MessageBox
+
+A globally-accessible modal dialog for confirmations and acknowledged messages. The `messageBox` singleton controller automatically mounts to `document.body` on first use, allowing any code in your application to call `messageBox.showInfo(...)` or `messageBox.showConfirm(...)` — no manual component mounting required. The dialog auto-focuses its primary action button, is draggable via the title bar, queues concurrent dialog requests sequentially, and resolves a `Promise<ModalResult>` when the user picks an action.
+
+## Features
+
+- **Auto-Mounted Singleton Controller**: Import `messageBox` and call `messageBox.showInfo` / `messageBox.showConfirm` directly.
+- **Concurrent Queuing**: Multiple dialog requests wait sequentially and resolve smoothly one by one.
+- **Two Flavors**: `showInfo` (single OK button) and `showConfirm` (OK + Cancel buttons).
+- **Typed Icons**: `info`, `warning`, `question` variants.
+- **Draggable**: Drag the title bar to reposition the dialog.
+- **Promise-Based**: `showConfirm` resolves with `ModalResult.MR_OK` or `ModalResult.MR_CANCEL`.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import messageBox, { ModalResult } from "@ticatec/topside-elements/MessageBox";
+```
+
+## Basic Usage
+
+Import `messageBox` and call `showInfo` or `showConfirm`:
+
+```svelte
+<script>
+  import messageBox, { ModalResult } from "@ticatec/topside-elements/MessageBox";
+
+  async function handleDelete() {
+    const res = await messageBox.showConfirm("Are you sure you want to delete this item?", {
+      title: "Delete Item",
+      type: "warning"
+    });
+    if (res === ModalResult.MR_OK) {
+      // Proceed with delete
+      messageBox.showInfo("Item deleted successfully.", { title: "Success" });
+    }
+  }
+</script>
+
+<button onclick={handleDelete}>Delete</button>
+```
+
+## API
+
+### `messageBox.showInfo(msg, options?)`
+
+Displays an informational dialog with an OK button. Returns `Promise<void>`.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `msg` | `string` | Required | Message content. |
+| `options.title` | `string` | App Title | Dialog header title text. |
+| `options.type` | `'info' \| 'warning'` | `'info'` | Icon category. |
+
+```typescript
+await messageBox.showInfo("Operation completed.", { title: "Notice", type: "info" });
+```
+
+### `messageBox.showConfirm(msg, options?)`
+
+Displays a confirmation dialog with OK and Cancel buttons. Returns `Promise<ModalResult>`.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `msg` | `string` | Required | Message content. |
+| `options.title` | `string` | App Title | Dialog header title text. |
+| `options.type` | `'warning' \| 'question'` | `'question'` | Icon category. |
+
+```typescript
+const result = await messageBox.showConfirm("Proceed with purchase?", { title: "Confirm", type: "question" });
+if (result === ModalResult.MR_OK) {
+  // Confirmed
+}
+```
+
+### `ModalResult` (enum)
+
+- `ModalResult.MR_OK` = 1
+- `ModalResult.MR_CANCEL` = 2
+- `ModalResult.MR_CLOSE` = 3
+
+## Related Components
+
+- [Indicator](../indicator/README.md) — Full-screen loading overlay.
+- [Toast](../toast/README.md) — Non-blocking transient notifications.
+- [Dialog](../dialog/README.md) — Centered modal for custom content.

package/dist/overlay/message-box/README_CN.md

@@ -0,0 +1,92 @@
+# MessageBox 消息框
+
+全功能模态确认与消息弹窗。`messageBox` 单例控制器会在首次使用时自动挂载至 `document.body`，应用内任何位置的代码都可以通过它调用 `messageBox.showInfo(...)` 或 `messageBox.showConfirm(...)`——无需手动挂载任何组件。弹窗支持自动聚焦主操作按钮、标题栏拖拽、并发弹窗队列化按顺序弹出，并在用户选择操作后返回 `Promise<ModalResult>`。
+
+## 特性
+
+- **自动挂载单例控制器**：直接导入 `messageBox` 并调用 `messageBox.showInfo` / `messageBox.showConfirm`
+- **并发请求队列**：多个并发弹窗自动按顺序排队并逐一展示与解决
+- **两种模式**：`showInfo` (单个确定按钮) 和 `showConfirm` (确定 + 取消按钮)
+- **图标类型**：`info`, `warning`, `question` 变体
+- **支持拖拽**：按住标题栏可拖拽移动弹窗位置
+- **基于 Promise**：`showConfirm` 在用户点击后返回 `ModalResult.MR_OK` 或 `ModalResult.MR_CANCEL`
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import messageBox, { ModalResult } from "@ticatec/topside-elements/MessageBox";
+```
+
+## 基础用法
+
+导入 `messageBox` 并调用 `showInfo` 或 `showConfirm`：
+
+```svelte
+<script>
+  import messageBox, { ModalResult } from "@ticatec/topside-elements/MessageBox";
+
+  async function handleDelete() {
+    const res = await messageBox.showConfirm("确定要删除该项吗？", {
+      title: "删除提示",
+      type: "warning"
+    });
+    if (res === ModalResult.MR_OK) {
+      // 执行删除
+      messageBox.showInfo("项目已成功删除。", { title: "成功" });
+    }
+  }
+</script>
+
+<button onclick={handleDelete}>删除</button>
+```
+
+## API
+
+### `messageBox.showInfo(msg, options?)`
+
+显示带“确定”按钮的信息弹窗。返回 `Promise<void>`。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `msg` | `string` | 必填 | 消息文本 |
+| `options.title` | `string` | 应用默认标题 | 弹窗标题文本 |
+| `options.type` | `'info' \| 'warning'` | `'info'` | 图标类型 |
+
+```typescript
+await messageBox.showInfo("操作已完成。", { title: "提示", type: "info" });
+```
+
+### `messageBox.showConfirm(msg, options?)`
+
+显示带“确定”和“取消”按钮的确认弹窗。返回 `Promise<ModalResult>`。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `msg` | `string` | 必填 | 消息文本 |
+| `options.title` | `string` | 应用默认标题 | 弹窗标题文本 |
+| `options.type` | `'warning' \| 'question'` | `'question'` | 图标类型 |
+
+```typescript
+const result = await messageBox.showConfirm("是否确认购买？", { title: "确认购买", type: "question" });
+if (result === ModalResult.MR_OK) {
+  // 确认
+}
+```
+
+### `ModalResult`（枚举）
+
+- `ModalResult.MR_OK` = 1
+- `ModalResult.MR_CANCEL` = 2
+- `ModalResult.MR_CLOSE` = 3
+
+## 相关组件
+
+- [Indicator](../indicator/README_CN.md) — 全屏加载指示器
+- [Toast](../toast/README_CN.md) — 非阻塞的临时通知
+- [Dialog](../dialog/README_CN.md) — 居中模态框

package/dist/overlay/message-box/index.d.ts

@@ -0,0 +1,5 @@
+import messageBox from "./MessageBox.svelte";
+import type IMessageBox from "./IMessageBox";
+import { ModalResult } from "./IMessageBox";
+export default messageBox;
+export { ModalResult, type IMessageBox };

package/dist/overlay/message-box/index.js

@@ -0,0 +1,4 @@
+import messageBox from "./MessageBox.svelte";
+import { ModalResult } from "./IMessageBox";
+export default messageBox;
+export { ModalResult };

package/dist/overlay/toast/README.md

@@ -0,0 +1,59 @@
+# Toast
+
+A lightweight, auto-dismissing notification banner. The `toast` singleton controller automatically mounts to `document.body` on first use, allowing any code in your application to fire non-blocking toast notifications — no manual component mounting required.
+
+## Features
+
+- **Auto-Mounted Singleton Controller**: Import `toast` and call `toast.show(...)` directly.
+- **Three Types**: `error` (red), `info` (blue), `success` (green).
+- **Auto-Dismiss**: Configurable duration in seconds; the toast fades out automatically.
+- **Portal to `document.body`**: Renders outside the component tree so it always sits above page content.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import toast from "@ticatec/topside-elements/Toast";
+```
+
+## Basic Usage
+
+Import `toast` and invoke `.show()`.
+
+```svelte
+<script>
+  import toast from "@ticatec/topside-elements/Toast";
+
+  function save() {
+    toast.show("Saved successfully.", "success", 3);
+  }
+</script>
+
+<button onclick={save}>Save</button>
+```
+
+## API
+
+### `toast.show(message, type, duration)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `message` | `string` | Required | Notification message text. |
+| `type` | `'info' \| 'success' \| 'error'` | `'info'` | Visual category determining icon and color token. |
+| `duration` | `number` | `3` | Display duration in seconds before auto-dismissing. |
+
+### Helper Methods
+
+- `toast.info(message, duration?)`
+- `toast.success(message, duration?)`
+- `toast.error(message, duration?)`
+
+## Related Components
+
+- [Indicator](../indicator/README.md) — Full-screen loading overlay.
+- [MessageBox](../message-box/README.md) — Modal confirmations and acknowledged messages.

package/dist/overlay/toast/README_CN.md

@@ -0,0 +1,59 @@
+# Toast 消息通知
+
+轻量级自动消除的通知横幅。`toast` 单例控制器会在首次使用时自动挂载至 `document.body`，应用内任何位置的代码都可以通过它触发非阻塞的通知提示——无需手动挂载任何组件。
+
+## 特性
+
+- **自动挂载单例控制器**：直接导入 `toast` 并调用 `toast.show(...)`
+- **三种类型**：`error` (红)、`info` (蓝)、`success` (绿)
+- **自动消除**：可配置持续秒数，超时后自动淡出
+- **挂载到 `document.body`**：渲染在组件树之外，确保始终显示在页面内容最上方
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import toast from "@ticatec/topside-elements/Toast";
+```
+
+## 基础用法
+
+导入 `toast` 并调用 `.show()`：
+
+```svelte
+<script>
+  import toast from "@ticatec/topside-elements/Toast";
+
+  function save() {
+    toast.show("保存成功。", "success", 3);
+  }
+</script>
+
+<button onclick={save}>保存</button>
+```
+
+## API
+
+### `toast.show(message, type, duration)`
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `message` | `string` | 必填 | 通知消息文本 |
+| `type` | `'info' \| 'success' \| 'error'` | `'info'` | 视觉类型，决定图标和颜色样式 |
+| `duration` | `number` | `3` | 自动消除前的显示时长（秒） |
+
+### 快捷方法
+
+- `toast.info(message, duration?)`
+- `toast.success(message, duration?)`
+- `toast.error(message, duration?)`
+
+## 相关组件
+
+- [Indicator](../indicator/README_CN.md) — 全屏加载指示器
+- [MessageBox](../message-box/README_CN.md) — 模态确认和消息弹窗

package/dist/overlay/toast/Toast.svelte.d.ts

@@ -0,0 +1,18 @@
+export type ToastType = 'error' | 'info' | 'success';
+declare class ToastController {
+    message: string;
+    type: ToastType;
+    visible: boolean;
+    contentHeight: number;
+    private interval;
+    private remaining;
+    /**
+     * 显示 toast 通知
+     */
+    show(msg: string, type?: ToastType, duration?: number): void;
+    info(msg: string, duration?: number): void;
+    success(msg: string, duration?: number): void;
+    error(msg: string, duration?: number): void;
+}
+declare const toast: ToastController;
+export default toast;

package/dist/overlay/toast/Toast.svelte.js

@@ -0,0 +1,49 @@
+import ToastPanel from './ToastPanel.svelte';
+import { createSingletonMounter } from '../common/mountSingleton';
+/**
+ * 懒挂载：第一次 show() 时把面板挂到 document.body，后续复用同一个实例。
+ * 不需要用户在 app 根节点手动挂 <ToastBoard />。
+ */
+const ensureMounted = createSingletonMounter(() => ToastPanel);
+class ToastController {
+    message = $state('');
+    type = $state('info');
+    visible = $state(false);
+    contentHeight = $state(0);
+    interval = null;
+    remaining = 0;
+    /**
+     * 显示 toast 通知
+     */
+    show(msg, type = 'info', duration = 3) {
+        ensureMounted();
+        this.message = msg;
+        this.type = type;
+        this.visible = true;
+        this.contentHeight = 48;
+        this.remaining = duration * 1000;
+        if (this.interval === null) {
+            this.interval = setInterval(() => {
+                this.remaining -= 100;
+                if (this.remaining <= 0) {
+                    this.visible = false;
+                    if (this.interval) {
+                        clearInterval(this.interval);
+                        this.interval = null;
+                    }
+                }
+            }, 100);
+        }
+    }
+    info(msg, duration = 3) {
+        this.show(msg, 'info', duration);
+    }
+    success(msg, duration = 3) {
+        this.show(msg, 'success', duration);
+    }
+    error(msg, duration = 3) {
+        this.show(msg, 'error', duration);
+    }
+}
+const toast = new ToastController();
+export default toast;

package/dist/overlay/toast/ToastPanel.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+    import { fly } from 'svelte/transition';
+    import toast from './Toast.svelte';
+
+    let contentHeight = $state(0);
+
+    // 当 toast 隐藏时，contentHeight 复位，让外层 div 高度塌回去
+    function handleOutroEnd() {
+        contentHeight = 0;
+    }
+
+    // visible 打开时把外层高度撑到 48px（toast 自身高度）
+    $effect(() => {
+        if (toast.visible) contentHeight = 48;
+    });
+</script>
+
+<div class="topside-toast-board" style="height: {contentHeight}px; top: 0;">
+    {#if toast.visible}
+        <div
+            transition:fly={{ duration: 300, y: '-100%' }}
+            onoutroend={handleOutroEnd}
+            class="{toast.type}"
+        >
+            <span>{toast.message}</span>
+        </div>
+    {/if}
+</div>
+
+<style>.topside-toast-board {
+  position: fixed;
+  left: 0;
+  right: 0;
+  top: 0;
+  background-color: var(--topside-color-overlay-mask-surface);
+  display: block;
+  text-align: center;
+  z-index: var(--topside-z-toast, 40);
+  color: var(--topside-toast-color);
+}
+.topside-toast-board .error {
+  background-color: var(--topside-toast-color-surface-error);
+}
+.topside-toast-board .info {
+  background-color: var(--topside-toast-color-surface-info);
+}
+.topside-toast-board .success {
+  background-color: var(--topside-toast-color-surface-success);
+}
+.topside-toast-board > div {
+  display: inline-block;
+  min-width: 300px;
+  padding: var(--topside-toast-margin);
+  border-radius: var(--topside-toast-radius);
+  font-size: var(--topside-toast-font-size);
+}</style>

package/dist/overlay/toast/ToastPanel.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const ToastPanel: import("svelte").Component<Record<string, never>, {}, "">;
+type ToastPanel = ReturnType<typeof ToastPanel>;
+export default ToastPanel;

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

@@ -0,0 +1,2 @@
+import toast from "./Toast.svelte";
+export default toast;

package/dist/overlay/toast/index.js

@@ -0,0 +1,2 @@
+import toast from "./Toast.svelte";
+export default toast;