@ticatec/topside-elements 1.0.0

package/dist/overlay/indicator/README.md

@@ -0,0 +1,142 @@
+# Indicator
+
+A full-screen loading indicator overlay. The `indicator` singleton controller automatically mounts to `document.body` on first use, allowing any code in your application to display or dismiss a centered loading spinner with a custom message. Ideal for blocking the UI during long-running operations such as data fetching, file processing, or multi-step submissions.
+
+## Features
+
+- **Full-Screen Overlay**: Semi-transparent backdrop blocks interaction with the underlying page.
+- **Auto-Mounted Singleton Controller**: Import and call `indicator.show()` / `indicator.hide()` directly without mounting any component manually.
+- **Custom Message**: Each `show()` takes a free-form status string.
+- **Portal to `document.body`**: Renders outside the component tree so it always overlays everything.
+- **Themeable**: Style entirely through CSS custom properties.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import indicator from "@ticatec/topside-elements/Indicator";
+```
+
+## Basic Usage
+
+Import `indicator` and invoke `.show()` or `.hide()`.
+
+```svelte
+<script>
+  import indicator from "@ticatec/topside-elements/Indicator";
+
+  function showIndicator() {
+    indicator.show("Loading...");
+    setTimeout(() => indicator.hide(), 5000);
+  }
+</script>
+
+<button onclick={showIndicator}>Show Indicator</button>
+```
+
+## API
+
+### `indicator.show(message)`
+
+Displays the overlay with a status message.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `message` | `string` | Required | The status text rendered next to the spinner. |
+
+### `indicator.hide()`
+
+Hides the overlay. Safe to call when the indicator is already hidden.
+
+## Examples
+
+### Async Data Fetch
+
+Always pair `show()` and `hide()` with `try/finally` so the indicator is dismissed even if the request fails.
+
+```svelte
+<script>
+  import indicator from "@ticatec/topside-elements/Indicator";
+
+  let users = [];
+
+  async function fetchUsers() {
+    indicator.show("Loading users...");
+    try {
+      const res = await fetch("/api/users");
+      users = await res.json();
+    } catch (err) {
+      console.error(err);
+    } finally {
+      indicator.hide();
+    }
+  }
+</script>
+
+<button onclick={fetchUsers}>Load</button>
+```
+
+### Sequential Status Updates
+
+Call `show()` repeatedly to update the message without flicker — the overlay stays visible.
+
+```svelte
+<script>
+  import indicator from "@ticatec/topside-elements/Indicator";
+
+  async function processBatch() {
+    indicator.show("Validating input...");
+    await delay(800);
+
+    indicator.show("Uploading files...");
+    await delay(1500);
+
+    indicator.show("Finalizing...");
+    await delay(600);
+
+    indicator.hide();
+  }
+
+  function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+</script>
+
+<button onclick={processBatch}>Run Batch</button>
+```
+
+## Styling
+
+The indicator is themed through CSS custom properties, declared on `:root` by `topside-root.scss`:
+
+```css
+:root {
+  /* Layout */
+  --topside-indicator-minimal-size: 300px;          /* content panel min-width */
+  --topside-indicator-content-margin: 16px 24px;    /* content panel padding */
+  --topside-indicator-content-spacing: 12px;        /* gap between spinner and text */
+  --topside-indicator-border-radius: var(--topside-radius-lg, 8px);
+
+  /* Colors */
+  --topside-color-overlay-mask-surface: rgba(255, 255, 255, 0.13);
+  --topside-indicator-color-surface: var(--topside-color-surface);
+  --topside-indicator-color-border: var(--topside-color-border-secondary);
+  --topside-indicator-color: var(--topside-color-secondary);
+  --topside-indicator-box-shadow:
+    rgba(17, 17, 26, 0.1) 0px 8px 24px,
+    rgba(17, 17, 26, 0.1) 0px 16px 56px,
+    rgba(17, 17, 26, 0.1) 0px 24px 80px;
+}
+```
+
+## Related Components
+
+- [MessageBox](../message-box/README.md) — Modal confirmations and acknowledged messages.
+- [Toast](../toast/README.md) — Non-blocking transient notifications.
+- [Dialog](../dialog/README.md) — Centered modal for custom content.
+- [Drawer](../drawer/README.md) — Slide-out side panel.

package/dist/overlay/indicator/README_CN.md

@@ -0,0 +1,142 @@
+# Indicator 加载指示器
+
+全屏加载指示器遮罩。`indicator` 单例控制器会在首次使用时自动挂载至 `document.body`，应用内任何位置的代码都可以通过它显示或隐藏一个居中的加载动画及状态文案。适用于数据拉取、文件处理、多步提交等耗时操作期间阻塞用户界面。
+
+## 特性
+
+- **全屏遮罩**：半透明背景层阻挡对底层页面的交互
+- **自动挂载单例控制器**：直接导入 `indicator.show()` / `indicator.hide()` 调用，无需手动挂载任何组件
+- **自定义文案**：每次 `show()` 都可以传入新的状态文本
+- **挂载到 `document.body`**：渲染在组件树之外，确保始终覆盖在所有内容之上
+- **可定制主题**：完全通过 CSS 自定义属性调整外观
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import indicator from "@ticatec/topside-elements/Indicator";
+```
+
+## 基础用法
+
+直接导入 `indicator` 并调用 `.show()` 或 `.hide()`。
+
+```svelte
+<script>
+  import indicator from "@ticatec/topside-elements/Indicator";
+
+  function showIndicator() {
+    indicator.show("加载中...");
+    setTimeout(() => indicator.hide(), 5000);
+  }
+</script>
+
+<button onclick={showIndicator}>显示指示器</button>
+```
+
+## API
+
+### `indicator.show(message)`
+
+显示遮罩并展示状态文案。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `message` | `string` | 必填 | 旋转图标旁显示的状态文本 |
+
+### `indicator.hide()`
+
+隐藏遮罩。在指示器已经隐藏时调用也是安全的。
+
+## 示例
+
+### 异步数据请求
+
+`show()` 与 `hide()` 必须搭配 `try/finally`，即使请求失败也能关闭指示器。
+
+```svelte
+<script>
+  import indicator from "@ticatec/topside-elements/Indicator";
+
+  let users = [];
+
+  async function fetchUsers() {
+    indicator.show("正在加载用户...");
+    try {
+      const res = await fetch("/api/users");
+      users = await res.json();
+    } catch (err) {
+      console.error(err);
+    } finally {
+      indicator.hide();
+    }
+  }
+</script>
+
+<button onclick={fetchUsers}>加载</button>
+```
+
+### 顺序更新的状态文案
+
+连续调用 `show()` 可以在遮罩不消失的情况下更新文案。
+
+```svelte
+<script>
+  import indicator from "@ticatec/topside-elements/Indicator";
+
+  async function processBatch() {
+    indicator.show("校验输入中...");
+    await delay(800);
+
+    indicator.show("上传文件中...");
+    await delay(1500);
+
+    indicator.show("正在收尾...");
+    await delay(600);
+
+    indicator.hide();
+  }
+
+  function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+</script>
+
+<button onclick={processBatch}>执行批处理</button>
+```
+
+## 样式
+
+指示器通过 CSS 自定义属性进行主题化，由 `topside-root.scss` 在 `:root` 上声明：
+
+```css
+:root {
+  /* 布局 */
+  --topside-indicator-minimal-size: 300px;          /* 内容面板最小宽度 */
+  --topside-indicator-content-margin: 16px 24px;    /* 内容面板内边距 */
+  --topside-indicator-content-spacing: 12px;        /* 旋转图标与文案之间的间距 */
+  --topside-indicator-border-radius: var(--topside-radius-lg, 8px);
+
+  /* 颜色 */
+  --topside-color-overlay-mask-surface: rgba(255, 255, 255, 0.13);  /* 共享遮罩色 */
+  --topside-indicator-color-surface: var(--topside-color-surface);
+  --topside-indicator-color-border: var(--topside-color-border-secondary);
+  --topside-indicator-color: var(--topside-color-secondary);
+  --topside-indicator-box-shadow:
+    rgba(17, 17, 26, 0.1) 0px 8px 24px,
+    rgba(17, 17, 26, 0.1) 0px 16px 56px,
+    rgba(17, 17, 26, 0.1) 0px 24px 80px;
+}
+```
+
+## 相关组件
+
+- [MessageBox](../message-box/README_CN.md) — 全局模态确认和消息
+- [Toast](../toast/README_CN.md) — 非阻塞的临时通知
+- [Dialog](../dialog/README_CN.md) — 居中模态框，可承载任意自定义内容
+- [Drawer](../drawer/README_CN.md) — 侧边滑出面板

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

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

package/dist/overlay/indicator/index.js

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

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

@@ -0,0 +1,17 @@
+export type ShowInfo = (message: string, options?: {
+    title?: string;
+    type?: 'warning' | 'info';
+}) => Promise<void>;
+export type ShowConfirm = (message: string, options?: {
+    title?: string;
+    type?: 'warning' | 'question';
+}) => Promise<any>;
+export default interface IMessageBox {
+    showInfo: ShowInfo;
+    showConfirm: ShowConfirm;
+}
+export declare enum ModalResult {
+    MR_OK = 1,
+    MR_CANCEL = 2,
+    MR_CLOSE = 3
+}

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

@@ -0,0 +1,6 @@
+export var ModalResult;
+(function (ModalResult) {
+    ModalResult[ModalResult["MR_OK"] = 1] = "MR_OK";
+    ModalResult[ModalResult["MR_CANCEL"] = 2] = "MR_CANCEL";
+    ModalResult[ModalResult["MR_CLOSE"] = 3] = "MR_CLOSE";
+})(ModalResult || (ModalResult = {}));

package/dist/overlay/message-box/MessageBox.svelte.d.ts

@@ -0,0 +1,36 @@
+import { ModalResult } from './IMessageBox';
+type InfoType = 'warning' | 'info';
+type ConfirmType = 'warning' | 'question';
+type MessageType = 'warning' | 'info' | 'question';
+interface MessageButton {
+    label: string;
+    type: string;
+    result: ModalResult;
+}
+declare class MessageBoxController {
+    visible: boolean;
+    title: string;
+    message: string;
+    type: MessageType;
+    iconType: string;
+    buttons: MessageButton[];
+    private resolve;
+    private queue;
+    private showMessageBox;
+    private displayMessage;
+    showInfo: (message: string, options?: {
+        title?: string;
+        type?: InfoType;
+    }) => Promise<void>;
+    showConfirm: (message: string, options?: {
+        title?: string;
+        type?: ConfirmType;
+    }) => Promise<any>;
+    /**
+     * 用户点了某个按钮（或关闭图标 / ESC）。
+     * 内部使用：由面板调用，触发外层的 Promise resolve。
+     */
+    resolveWith(result: ModalResult): void;
+}
+declare const messageBox: MessageBoxController;
+export default messageBox;

package/dist/overlay/message-box/MessageBox.svelte.js

@@ -0,0 +1,77 @@
+import MessageBoxPanel from './MessageBoxPanel.svelte';
+import { ModalResult } from './IMessageBox';
+import { getAppTitle } from '../../topsideContext';
+import i18nRes from '../../i18nRes';
+import { createSingletonMounter } from '../common/mountSingleton';
+const ensureMounted = createSingletonMounter(() => MessageBoxPanel);
+class MessageBoxController {
+    visible = $state(false);
+    title = $state('');
+    message = $state('');
+    type = $state('info');
+    iconType = $state('');
+    buttons = $state([]);
+    resolve = null;
+    queue = [];
+    showMessageBox(_message, _buttons, options) {
+        ensureMounted();
+        return new Promise((r) => {
+            const item = {
+                message: _message,
+                buttons: _buttons,
+                options,
+                resolve: r
+            };
+            if (this.visible || this.resolve != null) {
+                this.queue.push(item);
+            }
+            else {
+                this.displayMessage(item);
+            }
+        });
+    }
+    displayMessage(item) {
+        this.message = item.message;
+        this.title = item.options.title ?? getAppTitle();
+        this.buttons = item.buttons.map(b => ({ ...b, label: b.label }));
+        this.type = item.options?.type ?? 'info';
+        this.iconType = this.type === 'info' ? 'icon_google_info'
+            : this.type === 'warning' ? 'icon_google_warning'
+                : 'icon_google_help';
+        this.resolve = item.resolve;
+        this.visible = true;
+    }
+    showInfo = (_message, options = { type: 'info' }) => {
+        const infoButtons = [
+            { label: i18nRes.common.btnClose(), type: 'primary', result: ModalResult.MR_OK }
+        ];
+        return this.showMessageBox(_message, infoButtons, options);
+    };
+    showConfirm = (_message, options = { type: 'question' }) => {
+        const confirmButtons = [
+            { label: i18nRes.common.btnConfirm(), type: 'primary', result: ModalResult.MR_OK },
+            { label: i18nRes.common.btnCancel(), type: 'secondary', result: ModalResult.MR_CANCEL }
+        ];
+        return this.showMessageBox(_message, confirmButtons, options);
+    };
+    /**
+     * 用户点了某个按钮（或关闭图标 / ESC）。
+     * 内部使用：由面板调用，触发外层的 Promise resolve。
+     */
+    resolveWith(result) {
+        if (this.resolve != null) {
+            const res = this.resolve;
+            this.resolve = null;
+            res(result);
+        }
+        if (this.queue.length > 0) {
+            const nextItem = this.queue.shift();
+            this.displayMessage(nextItem);
+        }
+        else {
+            this.visible = false;
+        }
+    }
+}
+const messageBox = new MessageBoxController();
+export default messageBox;

package/dist/overlay/message-box/MessageBoxPanel.svelte

@@ -0,0 +1,247 @@
+<script lang="ts">
+    import {tick} from "svelte";
+    import Button from "../../general/button";
+    import utils from "../common/utils";
+    import messageBox from "./MessageBox.svelte";
+
+    let dialogEl: HTMLDialogElement | null = $state(null);
+
+    let top = $state(0);
+    let left = $state(0);
+    let startMove = $state(false);
+
+    const handleMouseDown = () => {
+        startMove = true;
+    };
+
+    const handleMouseMove = (e: MouseEvent) => {
+        if (startMove) {
+            top = top + e.movementY;
+            left = left + e.movementX;
+        }
+    };
+
+    const handleMouseUp = () => {
+        startMove = false;
+    };
+
+    const handleCloseClick = () => {
+        messageBox.resolveWith(2); // ModalResult.MR_CANCEL
+    };
+
+    // 监听 visible，触发原生 dialog 的显隐
+    $effect(() => {
+        if (dialogEl) {
+            if (messageBox.visible) {
+                top = 0;
+                left = 0;
+                startMove = false;
+                if (typeof dialogEl?.showModal === 'function') {
+                    dialogEl.showModal();
+                }
+                setTimeout(() => {
+                    let firstButton = dialogEl?.querySelector('button');
+                    if (firstButton) {
+                        firstButton.focus();
+                    }
+                }, 500);
+            } else if (dialogEl.open) {
+                dialogEl.close();
+            }
+        }
+    });
+
+    const handleDialogCancel = (e: Event) => {
+        e.preventDefault();
+        handleCloseClick();
+    };
+</script>
+
+<dialog bind:this={dialogEl} class="topside-message-dialog" oncancel={handleDialogCancel}>
+    <div style={startMove ? 'cursor: move' : ''} onmousemove={handleMouseMove} role="none" class="dialog-inner">
+        <div class="topside-message-box">
+            <div style="top: {top}px; left: {left}px">
+                <!-- Drag handle for repositioning the dialog, not a semantic control; the
+                     close action inside it is its own focusable <button>. -->
+                <!-- svelte-ignore a11y_no_static_element_interactions -->
+                <div class="title-bar" onmousedown={handleMouseDown} onmouseup={handleMouseUp}>
+                    {#if !utils.isEmpty(messageBox.title)}
+                        <span class="title-text">{messageBox.title}</span>
+                    {/if}
+                    <div>
+                        <button type="button" class="dialog-action-button" aria-label="Close" onclick={handleCloseClick}>
+                            <i class="icon_google_clear" aria-hidden="true"></i>
+                        </button>
+                    </div>
+                </div>
+                <div class="box-content">
+                    {#if messageBox.iconType}
+                        <div class="box-icon {messageBox.type}">
+                            <i class={messageBox.iconType}></i>
+                        </div>
+                    {/if}
+                    <div class="message-text">
+                        <span>{messageBox.message}</span>
+                    </div>
+                </div>
+                <div class="control-bar">
+                    {#if messageBox.buttons.length > 0}
+                        {#each messageBox.buttons as button, idx}
+                            <Button style="margin: 0 4px; width: 90px" type={button.type as any} label={button.label} autofocus={idx==0}
+                                    onclick={() => messageBox.resolveWith(button.result)}/>
+                        {/each}
+                    {/if}
+                </div>
+            </div>
+        </div>
+    </div>
+</dialog>
+
+<style>.topside-message-dialog {
+  border: none;
+  background: transparent;
+  padding: 0;
+  margin: 0;
+  max-width: 100vw;
+  max-height: 100vh;
+  width: 100%;
+  height: 100%;
+  user-select: none;
+  z-index: var(--topside-z-message-box, 30);
+  opacity: 0;
+  transition: opacity 0.3s ease, display 0.3s ease allow-discrete, overlay 0.3s ease allow-discrete;
+}
+.topside-message-dialog[open] {
+  opacity: 1;
+}
+@starting-style {
+  .topside-message-dialog[open] {
+    opacity: 0;
+  }
+}
+.topside-message-dialog::backdrop {
+  background-color: var(--topside-color-dialog-mask-surface);
+  opacity: 0;
+  transition: opacity 0.3s ease, display 0.3s ease allow-discrete, overlay 0.3s ease allow-discrete;
+}
+.topside-message-dialog[open]::backdrop {
+  opacity: 1;
+}
+@starting-style {
+  .topside-message-dialog[open]::backdrop {
+    opacity: 0;
+  }
+}
+.topside-message-dialog .dialog-inner {
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  width: 100%;
+  height: 100%;
+  justify-content: center;
+}
+.topside-message-dialog .topside-message-box {
+  height: 90%;
+  position: relative;
+  overflow: hidden;
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  padding: 40px;
+}
+.topside-message-dialog .topside-message-box > div {
+  margin: 0 auto;
+  width: var(--topside-message-box-width);
+  position: relative;
+  background-color: var(--topside-message-box-color-surface);
+  border-radius: var(--topside-message-box-radius);
+  border: 1px solid var(--topside-color-border-secondary);
+  box-shadow: var(--topside-messagebox-shadow);
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  font-size: 1rem;
+  max-height: 100%;
+}
+.topside-message-dialog .topside-message-box .box-icon {
+  flex: 0 0 auto;
+  padding: var(--topside-message-box-margin);
+  margin-right: var(--topside-message-box-spacing);
+  flex-direction: row;
+  display: flex;
+  align-items: center;
+  font-size: var(--topside-message-box-icon-size);
+}
+.topside-message-dialog .topside-message-box .box-icon.warning {
+  color: var(--topside-message-color-warning);
+}
+.topside-message-dialog .topside-message-box .box-icon.question {
+  color: var(--topside-message-color-question);
+}
+.topside-message-dialog .topside-message-box .box-icon.info {
+  color: var(--topside-message-color-info, #2563eb);
+}
+.topside-message-dialog .topside-message-box .title-bar {
+  width: 100%;
+  height: var(--topside-message-box-title-height);
+  box-sizing: border-box;
+  font-size: 1.15em;
+  color: var(--topside-message-color-title-bar);
+  border-bottom: 1px solid var(--topside-message-color-title-bar-border);
+  padding: var(--topside-message-box-title-bar-margin);
+  flex: 0 0 auto;
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: flex-end;
+}
+.topside-message-dialog .topside-message-box .title-bar .title-text {
+  margin-right: auto;
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.topside-message-dialog .topside-message-box .title-bar .dialog-action-button {
+  cursor: pointer;
+  color: var(--topside-message-color-title-bar);
+  background: none;
+  border: none;
+  padding: 4px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font: inherit;
+}
+.topside-message-dialog .topside-message-box .title-bar .dialog-action-button:hover {
+  background-color: var(--topside-dialog-action-button-color-hover-surface);
+  border-radius: 4px;
+}
+.topside-message-dialog .topside-message-box .title-bar .dialog-action-button:active {
+  position: relative;
+  top: 1px;
+}
+.topside-message-dialog .topside-message-box .title-bar .dialog-action-button:focus-visible {
+  outline: 2px solid var(--topside-primary-border-color, #298DFF);
+  outline-offset: 1px;
+}
+.topside-message-dialog .box-content {
+  flex: 1 1 auto;
+  overflow: auto;
+  display: flex;
+  flex-direction: row;
+  justify-items: center;
+  padding: var(--topside-message-box-content-margin);
+  line-height: 1.5em;
+  color: var(--topside-color-primary);
+}
+.topside-message-dialog .box-content .message-text {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+}
+.topside-message-dialog .control-bar {
+  flex: 0 0 auto;
+  text-align: var(--topside-message-box-action-bar-text-align);
+  padding: var(--topside-message-box-action-bar-margin);
+}</style>

package/dist/overlay/message-box/MessageBoxPanel.svelte.d.ts

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