@ticatec/topside-elements 1.0.0

package/dist/overlay/context-menu/README_CN.md

@@ -0,0 +1,361 @@
+# ContextMenu 右键菜单
+
+带完整键盘导航、焦点管理和 ARIA 支持的右键上下文菜单。在 `contextmenu` 事件回调里调用 `contextMenu.show(event, items)`，就会在光标位置弹出 `ContextMenuItem` 列表。菜单会自动避让视窗边缘，打开时锁定键盘焦点，并通过点击外部、Escape 或焦点离开关闭。
+
+## 架构
+
+ContextMenu 是一个**单例控制器**加一个内部**面板组件**，面板在首次使用时自动挂载：
+
+- **`contextMenu`（单例）** —— 一个持有 `$state`（`visible`、`position`、`items`、`theme` ……）的模块级实例。在任何地方 import 它，调用 `.show(...)` / `.hide()` 来驱动菜单。
+- **面板（内部）** —— 第一次 `show()` 调用时通过 Svelte 的 `mount()` 把面板懒挂载到 `document.body`。后续调用复用同一个实例。**不需要在任何地方挂 `<ContextMenu />`。**
+
+与 `MessageBox`、`Toast`、`Indicator` 一样，`ContextMenu` 采用自动挂载的单例控制器模式：所有这些控制器均在首次使用时自动将内部面板挂载至 `document.body`，无需在组件树中显式挂载 Board 组件。
+
+## 特性
+
+- **右键触发**：基于原生 `contextmenu` 事件
+- **零设置**：只 import `contextMenu` 然后调 `show()`，面板首次使用时自己挂上
+- **完整键盘导航**：
+  - **方向键 ↑/↓**：在菜单项之间移动焦点（跳过 disabled 和 separator，循环滚动）
+  - **Enter / 空格**：执行当前聚焦项
+  - **Escape**：关闭菜单
+  - **Tab**：被拦截——`preventDefault` 让焦点留在菜单内
+- **焦点管理**：打开时焦点自动移到菜单容器；`aria-activedescendant` 跟踪当前聚焦项，供屏幕阅读器播报
+- **边缘感知定位**：x/y 自动收敛，确保菜单不会超出视窗
+- **多种关闭路径**：点击外部、Escape、或焦点离开都会关闭
+- **悬停与键盘同步**：鼠标悬停更新同一个 `.focused` 状态，与键盘导航的高亮视觉完全统一
+- **禁用项与分隔符**：禁用项变暗且不可交互；分隔符渲染为水平分隔线
+- **菜单项图标**：可选的 `icon` URL，渲染为 16×16 缩略图
+- **按次主题**：`show()` 的第 5 个参数可选地渲染为根元素的 `data-theme` —— 适用于"浅色页面里要开深色抽屉菜单"之类的场景
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import contextMenu, { type ContextMenuItem, type ActionCallback } from "@ticatec/topside-elements/ContextMenu";
+```
+
+（`contextMenu` 也可作为命名导入：`import { contextMenu } from …`。）
+
+## 基础用法
+
+import 单例，在任何 `contextmenu` 回调里调 `show()`。**不需要在 app 根挂任何东西** —— 面板首次使用时自动挂。
+
+```svelte
+<script lang="ts">
+  import contextMenu from "@ticatec/topside-elements/ContextMenu";
+
+  const items = [
+    { text: "复制",  action: () => console.log("copy") },
+    { text: "粘贴",  action: () => console.log("paste") },
+    { separator: true },
+    { text: "删除",  action: () => console.log("delete") }
+  ];
+</script>
+
+<div oncontextmenu={(e) => contextMenu.show(e, items)}>
+  右键此处
+</div>
+```
+
+## API
+
+### `contextMenu` 单例
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `show` | `(event: MouseEvent, items: ContextMenuItem[], width?: number, height?: number, theme?: string) => void` | 在 `event.clientX/Y` 处打开菜单，位置自动收敛到视窗内。内部会调用 `event.preventDefault()`。`width` / `height` 默认 `150`，既用于面板的 min-size，也用于避让视窗边缘的计算。`theme`（可选）会作为 `data-theme` 渲染到菜单根上，便于作用域样式覆盖。**首次调用会懒挂载面板到 `document.body`。** 已打开时再次调用会先重置状态再在新位置渲染 |
+| `hide` | `() => void` | 关闭菜单。已关闭时为 no-op |
+
+控制器还暴露了它的 `$state` 字段（`visible`、`position`、`items`、`width`、`height`、`theme`）—— 可读，但一般无需直接访问。
+
+### `ContextMenuItem`
+
+```typescript
+interface ContextMenuItem {
+  text: string;            // 必填：标签文本
+  action?: () => void;     // 点击或 Enter/空格时执行（disabled/separator 项会跳过）
+  disabled?: boolean;      // 变暗、不可交互，键盘导航也会跳过
+  separator?: boolean;     // 渲染为水平分隔线（其它字段被忽略）
+  icon?: string;           // 图片 URL/路径，渲染为 16×16 <img>
+  style?: string;          // 仅作用于该项的内联 CSS
+}
+```
+
+### `ActionCallback`
+
+```typescript
+type ActionCallback = () => void;
+```
+
+### `OnContextMenu`
+
+```typescript
+type OnContextMenu = (event: MouseEvent, data: any) => void;
+```
+
+**给你自己**的 `contextmenu` handler 用的便利类型 —— 控制器本身不是这个签名（它取 `(event, items, …)`）。当你想要一个有类型的 wrapper，把每个目标的数据跟事件一起捕获时使用：
+
+```svelte
+<script lang="ts">
+  import { contextMenu, type OnContextMenu } from "@ticatec/topside-elements/ContextMenu";
+
+  // 有类型的 handler —— `data` 是用户右键的那一行
+  const handleContext: OnContextMenu = (event, data) => {
+    contextMenu.show(event, buildItemsFor(data));
+  };
+</script>
+
+{#each rows as row}
+  <div oncontextmenu={(e) => handleContext(e, row)}>{row.name}</div>
+{/each}
+```
+
+## 键盘导航
+
+| 按键 | 行为 |
+|------|------|
+| **方向键 ↓** | 焦点移到下一个可点击项（循环到顶部） |
+| **方向键 ↑** | 焦点移到上一个可点击项（循环到底部） |
+| **Enter / 空格** | 执行当前聚焦项的 `action` 并关闭 |
+| **Escape** | 关闭菜单 |
+| **Tab** | 被拦截——菜单关闭前焦点不会离开 |
+
+禁用项与分隔符会被跳过。`moveSelection` 算法先算出可点击项的索引列表，再循环遍历。
+
+## 行为
+
+### 打开流程
+
+1. 调用者在事件回调里调用 `contextMenu.show(event, items, …)`。
+2. **仅首次调用**：`show()` 检查面板是否已挂；若未挂，通过 `mount(ContextMenuPanel, { target: document.body })` 懒挂载，并标记为已挂。后续调用跳过这步。
+3. `show()` 调 `event.preventDefault()`，先把 `visible` 置回 `false`（如果已有菜单打开，强制一次干净的重渲染）。
+4. 把 `items` / `width` / `height` / `theme` 写入状态，按视窗收敛 `x` / `y`，再把 `visible` 翻成 `true`。
+5. 面板的 `$effect` 捕获到变化，把 `focusedIndex` 重置为 `-1`，`await tick()` 后对面板根调用 `.focus()` —— 后续键盘事件才会落在菜单上。
+
+> **`event.preventDefault()` 必须同步执行。** 如果你的 `contextmenu` handler 是 `async` 的，在调 `contextMenu.show(event, …)` 之前 `await` 了什么东西，浏览器已经弹出原生右键菜单了 —— `show()` 内部的 `preventDefault()` 为时已晚。任何异步工作放到 `show()` 之后做（比如 fetch 最新 items，再用新列表二次调 `show()`）。
+
+### 关闭流程
+
+关闭通过面板的 `onblur` 处理（没有全局 window 监听）：
+
+- **点击外部**：点击菜单外区域时焦点移到 `document.body` 或其它元素 → `onblur` 触发 → 如果 `relatedTarget` 在面板外，调用 `hide()`。
+- **Escape 键**：`handleKeyDown` 直接调用 `hide()`。
+- **菜单项点击 / Enter / 空格**：执行 `action` 后调 `hide()`。
+- **编程式 `hide()`**：随时可调；已关闭时为 no-op。
+
+如果 `relatedTarget` 在面板**内部**（如焦点在子项之间转移），blur 会被忽略——只有焦点真正离开菜单才会关闭。
+
+### ARIA
+
+- 菜单根有 `role="menu"`，菜单项 `role="menuitem"`，分隔符 `role="separator"`
+- 根上的 `aria-activedescendant` 跟随聚焦项的 `id`（`topside-menu-item-{index}`），屏幕阅读器无需移动 DOM 焦点即可播报高亮项
+- 禁用项带 `aria-disabled`
+
+## 样式
+
+面板读取以下 CSS 自定义属性。默认值由 `topside-root.scss` 提供，**变量名一致**——覆盖 root token 或在局部作用域重新定义都可以。
+
+```scss
+.topside-context-menu {
+  background-color: var(--topside-contextmenu-color-surface);
+  color: var(--topside-contextmenu-color);
+  border: 1px solid var(--topside-color-border-secondary);
+  box-shadow: var(--topside-contextmenu-shadow);
+  padding: var(--topside-contextmenu-margin);
+  min-width: var(--topside-contextmenu-minimal-width);
+  min-height: var(--topside-contextmenu-minimal-height);
+
+  .menu-item {
+    padding: var(--topside-contextmenu-item-margin);
+    gap: var(--topside-contextmenu-spacing);
+    border-radius: var(--topside-radius);
+    // hover / focused 背景 / 文本色：
+    background-color: var(--topside-contextmenu-color-hover-surface);
+    color: var(--topside-contextmenu-color-hover);
+  }
+
+  .menu-separator {
+    background-color: var(--topside-contextmenu-color-separator);
+    margin: var(--topside-contextmenu-separator-margin) 0;
+  }
+}
+```
+
+| 变量 | `topside-root.scss` 中的默认值 |
+|------|-------------------------------|
+| `--topside-contextmenu-color-surface` | `var(--topside-color-surface)`（解析为当前主题的表面色） |
+| `--topside-contextmenu-color` | `var(--topside-color-primary)`（解析为当前主题的文本色） |
+| `--topside-color-border-secondary` | 浅色 `#e5e7eb` / 深色 `#2d2d2d`（共享边框 token，与 Box / Indicator / Editor 同源） |
+| `--topside-contextmenu-shadow` | `0 2px 4px -1px rgba(0,0,0,0.06), 0 4px 12px rgba(0,0,0,0.08)` |
+| `--topside-contextmenu-margin` | `6px 8px` |
+| `--topside-contextmenu-minimal-width` | `150px` |
+| `--topside-contextmenu-minimal-height` | `100px` |
+| `--topside-contextmenu-item-margin` | `8px` |
+| `--topside-contextmenu-spacing` | `8px` |
+| `--topside-contextmenu-separator-margin` | `8px` |
+| `--topside-contextmenu-color-hover-surface` | `#f3f4f6` |
+| `--topside-contextmenu-color-hover` | `#111827` |
+| `--topside-contextmenu-color-separator` | `#e5e7eb` |
+
+因为 surface / text / border token 都最终透传到主题层的 `--topside-color-*` 变量，**深色模式自动生效** —— `topside-root.scss` 的 `[data-theme="dark"]` 块覆盖了那些主题 token，菜单会跟着切换。
+
+### 自定义样式
+
+```css
+/* 重新品牌化菜单表面 */
+:root {
+  --topside-contextmenu-color-surface: #ffffff;
+  --topside-contextmenu-color: #1f2937;
+}
+
+/* 更紧凑的菜单 */
+:root {
+  --topside-contextmenu-margin: 4px;
+  --topside-contextmenu-item-margin: 6px;
+  --topside-contextmenu-spacing: 6px;
+}
+```
+
+### 按次主题
+
+向 `show()` 第 5 个参数传 `theme` 字符串，CSS 里针对 `[data-theme="…"].topside-context-menu` 写覆盖样式：
+
+```svelte
+<script>
+  // 浅色页面里要打开深色面板的菜单
+  function onDarkPanelContext(e) {
+    contextMenu.show(e, items, 150, 150, "dark-panel");
+  }
+</script>
+
+<style>
+  :global([data-theme="dark-panel"].topside-context-menu) {
+    background-color: #1f2937;
+    color: #f9fafb;
+  }
+</style>
+```
+
+## 示例
+
+### 带图标与禁用项
+
+```svelte
+<script>
+  import { contextMenu } from "@ticatec/topside-elements/ContextMenu";
+
+  let clipboardEmpty = true;
+
+  const items = [
+    { text: "剪切", action: () => cut() },
+    { text: "复制", action: () => copy() },
+    { text: "粘贴", action: () => paste(), disabled: clipboardEmpty },
+    { separator: true },
+    { text: "删除", action: () => del() }
+  ];
+</script>
+
+<div oncontextmenu={(e) => contextMenu.show(e, items)}>
+  右键打开编辑菜单
+</div>
+```
+
+### 按目标动态生成
+
+```svelte
+<script>
+  import { contextMenu } from "@ticatec/topside-elements/ContextMenu";
+
+  function itemsFor(node) {
+    const items = [{ text: "属性", action: () => showProps(node) }];
+    if (node.type === "file") {
+      items.unshift(
+        { text: "打开", action: () => open(node) },
+        { separator: true }
+      );
+    }
+    return items;
+  }
+</script>
+
+{#each nodes as node}
+  <div oncontextmenu={(e) => contextMenu.show(e, itemsFor(node))}>
+    {node.name}
+  </div>
+{/each}
+```
+
+### 键盘触发
+
+组件本身不提供键盘入口——用标准的 **Shift+F10** 自行接入：
+
+```svelte
+<script>
+  import { contextMenu } from "@ticatec/topside-elements/ContextMenu";
+
+  let triggerEl;
+
+  const items = [
+    { text: "重命名", action: () => rename() },
+    { text: "删除",   action: () => del() }
+  ];
+
+  function handleKeydown(e) {
+    if ((e.shiftKey && e.key === "F10") || e.key === "ContextMenu") {
+      e.preventDefault();
+      const rect = triggerEl.getBoundingClientRect();
+      const fakeEvent = {
+        preventDefault: () => {},
+        clientX: rect.left,
+        clientY: rect.bottom
+      };
+      contextMenu.show(fakeEvent as MouseEvent, items);
+    }
+  }
+</script>
+
+<span
+  bind:this={triggerEl}
+  tabindex="0"
+  oncontextmenu={(e) => contextMenu.show(e, items)}
+  onkeydown={handleKeydown}
+>
+  右键点击，或按 Shift+F10
+</span>
+```
+
+## 最佳实践
+
+1. **零设置。** 只要 `import contextMenu` 在 `contextmenu` handler 里调 `show()` —— 面板首次使用时自动挂
+2. **嵌套触发点时记得阻止冒泡**：`oncontextmenu={(e) => { e.stopPropagation(); contextMenu.show(e, items); }}`
+3. **不可用的操作设禁用而不是隐藏**——用户能从灰项中学到"这个菜单可以做哪些事"
+4. **用分隔符给相关操作分组**——超过 6–7 个无分组的项会降低扫读效率
+5. **标签简短、动词开头**——"删除"、"重命名"、"属性"
+6. **图标用小图**——按 16×16、`object-fit: contain` 渲染，大图会被缩小
+7. **不要尝试同时开两个菜单。** 控制器是单例——已打开时再调 `show()` 会重置状态后在新位置重新打开
+8. **提供键盘入口**——Shift+F10 是惯例，参见上方示例
+
+## 无障碍
+
+组件实现了标准的菜单键盘模型（ARIA Authoring Practices）：
+
+- `role="menu"` / `role="menuitem"` / `role="separator"`
+- `aria-activedescendant` 跟随键盘焦点
+- 禁用项带 `aria-disabled`
+- 完整键盘支持（方向键、Enter、空格、Escape、Tab trap）
+- 打开时焦点移到菜单，关闭时回到合理状态
+
+## 相关组件
+
+- [Dialog](../dialog/README_CN.md) — 居中模态框，可承载任意自定义内容
+- [MessageBox](../message-box/README_CN.md) — 全局模态确认和消息
+- [Toast](../toast/README_CN.md) — 非阻塞的临时通知
+- [Indicator](../indicator/README_CN.md) — 全屏加载指示器
+- [Drawer](../drawer/README_CN.md) — 侧边滑出面板
+- [Tooltip](../tooltip/README_CN.md) — 悬停式上下文提示

package/dist/overlay/context-menu/index.d.ts

@@ -0,0 +1,6 @@
+import contextMenu from "./ContextMenu.svelte";
+import type { ContextMenuItem } from "./ContextMenuItem.js";
+import type { OnContextMenu, ContextMenuAction } from "./ContextMenuItem.js";
+export default contextMenu;
+export { contextMenu };
+export type { ContextMenuItem, OnContextMenu, ContextMenuAction };

package/dist/overlay/context-menu/index.js

@@ -0,0 +1,3 @@
+import contextMenu from "./ContextMenu.svelte";
+export default contextMenu;
+export { contextMenu };

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

@@ -0,0 +1,4 @@
+/**
+ * 关闭前的否决钩子（NAMING R2）：结果为 MR_CANCEL / MR_CLOSE 时调用，返回 false 阻止关闭。
+ */
+export type BeforeClose = () => boolean | void | Promise<boolean | void>;

package/dist/overlay/dialog/BeforeClose.js

@@ -0,0 +1 @@
+export {};

package/dist/overlay/dialog/CommonDialog.svelte

@@ -0,0 +1,58 @@
+<script lang="ts">
+    import type {Snippet} from 'svelte';
+    import Dialog from "./Dialog.svelte";
+    import type {ButtonAction, ButtonActions} from "../../types";
+    import type {BeforeClose} from "./BeforeClose";
+    import {ModalResult, type OnClose} from "./IDialog";
+    import i18nRes from "../../i18nRes";
+
+    interface Props {
+        title: string;
+        width?: string;
+        height?: string;
+        /** 关闭前的否决钩子：结果为 MR_CANCEL / MR_CLOSE 时调用，返回 false 阻止关闭 */
+        beforeClose?: BeforeClose | null;
+        content$style?: string;
+        /** 确认按钮是否可用 */
+        confirmable?: boolean;
+        /** 点击确认时调用；返回 truthy 值则以 MR_OK 关闭 */
+        onconfirm?: (() => Promise<any>) | null;
+        confirmText?: string | null;
+        /** 关闭后的通知回调，参数为 ModalResult */
+        onclose?: OnClose | null;
+        children?: Snippet;
+    }
+
+    let {
+        title,
+        width = 'unset',
+        height = 'unset',
+        beforeClose = null,
+        content$style = '',
+        confirmable = true,
+        onconfirm = null,
+        confirmText = null,
+        onclose = null,
+        children
+    }: Props = $props();
+
+    let dialog: Dialog;
+
+    const confirmAction = $derived<ButtonAction>({
+        label: confirmText ?? i18nRes.common.btnConfirm(),
+        type: "primary",
+        disabled: onconfirm == null || !confirmable,
+        handler: async () => {
+            const result = await onconfirm?.();
+            if (result && result == true) { // 返回 true 自动关闭
+                await dialog.close(ModalResult.MR_OK);
+            }
+        }
+    });
+
+    const actions = $derived<ButtonActions>([confirmAction]);
+</script>
+
+<Dialog bind:this={dialog} {title} {content$style} {width} {height} {actions} {beforeClose} {onclose}>
+    {@render children?.()}
+</Dialog>

package/dist/overlay/dialog/CommonDialog.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { Snippet } from 'svelte';
+import type { BeforeClose } from "./BeforeClose";
+import { type OnClose } from "./IDialog";
+interface Props {
+    title: string;
+    width?: string;
+    height?: string;
+    /** 关闭前的否决钩子：结果为 MR_CANCEL / MR_CLOSE 时调用，返回 false 阻止关闭 */
+    beforeClose?: BeforeClose | null;
+    content$style?: string;
+    /** 确认按钮是否可用 */
+    confirmable?: boolean;
+    /** 点击确认时调用；返回 truthy 值则以 MR_OK 关闭 */
+    onconfirm?: (() => Promise<any>) | null;
+    confirmText?: string | null;
+    /** 关闭后的通知回调，参数为 ModalResult */
+    onclose?: OnClose | null;
+    children?: Snippet;
+}
+declare const CommonDialog: import("svelte").Component<Props, {}, "">;
+type CommonDialog = ReturnType<typeof CommonDialog>;
+export default CommonDialog;