dsh-plugin-core 0.31.0 → 0.33.0

package/dist/ui/feedback/LoaderBar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoaderBar.d.ts","sourceRoot":"","sources":["../../../src/ui/feedback/LoaderBar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,aAAa,IAAI,CAAC,EAAS,MAAM,OAAO,CAAA;AAIjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAuB7C,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAoDrE"}

package/dist/ui/feedback/LoaderBar.js

@@ -0,0 +1,79 @@
+/**
+ * LoaderBar —— 胶囊不定进度 loading（Loader 家族成员）。
+ *
+ * 图形来源：设计出的「轨道 + 蓝色段 + 斜纹」胶囊条。动画是**不定进度**语义：
+ * 蓝色那半截**固定不动**，只有它上面的一道道细斜纹单向流动（0.55 秒走一个条纹周期），
+ * 看着像条纹在转，不表示任何百分比。要「确定进度」别改这个控件 —— 它是固定加载态，
+ * 不是进度条 API。
+ *
+ * 尺寸轴按**高度**给（宽固定 4:1）：图形本身是横条，套方形的尺寸轴没意义。
+ *
+ * 实现要点：外层 `<g clip-path>` 静止、只让内层的蓝色段动。若把 `clip-path` 与
+ * `transform` 放在同一层，裁剪框会跟着平移，等于没裁，蓝段会跑出胶囊外。
+ * clipPath 的 id 由 `useId` 生成（同一页面可能有多个实例，写死 id 会互相抢）。
+ *
+ * 边界同 `Loader`：不带背景、不带内距、不带定位。
+ *
+ * ⚠️ 图形数据在 `loader-bar-art.ts`（源 SVG 一次性转录），别手改坐标。
+ */
+import { createElement as h, useId } from 'react';
+import { ensureComponentStyles } from '../infra/css.js';
+import { LOADER_BAR_CSS } from '../infra/controls-css.js';
+import { BAR_PATHS } from './loader-bar-art.js';
+/** 源图三条路径的固定顺序：轨道 / 蓝色段 / 斜纹。 */
+const TRACK_INDEX = 0;
+const FILL_INDEX = 1;
+const STRIPE_INDEX = 2;
+/**
+ * 斜纹的横向重复周期（用户单位）：源图相邻斜线的间距。
+ * 平移整整一个周期后与原图重合 ⇒ 循环无缝。
+ * ⚠️ 必须与 `loader-bar.css` 里 `translateX(85.333px)` 保持一致。
+ */
+const STRIPE_PERIOD = 85.333;
+/** 取第 index 条路径：转录不全就当场抛，别静默少画一块。 */
+function pathAt(paths, index) {
+    const path = paths[index];
+    if (path === undefined) {
+        throw new Error(`loader-bar-art 缺少第 ${String(index)} 条路径`);
+    }
+    return path;
+}
+/**
+ * 渲染胶囊不定进度 loading。
+ *
+ * @param props 见 {@link LoaderBarProps}。
+ * @returns `<svg>` 元素。
+ */
+export function LoaderBar(props) {
+    ensureComponentStyles('loader-bar', LOADER_BAR_CSS);
+    const { size = 'md', animated = true, label, className } = props;
+    // useId 返回形如 `:r0:` 的串，冒号放进 url(#…) 需要转义，这里直接剔掉。
+    const clipId = `dshpc-loader-bar-clip-${useId().replace(/[^a-zA-Z0-9_-]/g, '')}`;
+    const track = pathAt(BAR_PATHS, TRACK_INDEX);
+    const fill = pathAt(BAR_PATHS, FILL_INDEX);
+    const stripe = pathAt(BAR_PATHS, STRIPE_INDEX);
+    const classes = ['dshpc-loader-bar', `dshpc-loader-bar--${size}`];
+    if (animated === false)
+        classes.push('dshpc-loader-bar--still');
+    if (className !== undefined && className !== '')
+        classes.push(className);
+    return h('svg', {
+        className: classes.join(' '),
+        viewBox: '0 384 1024 256',
+        role: label === undefined ? undefined : 'status',
+        'aria-label': label,
+        'aria-hidden': label === undefined ? true : undefined,
+        focusable: 'false',
+    }, h('defs', null, 
+    // 直接拿「蓝色段」自己的路径当裁剪区：它左端是圆的、**右端是平直的**
+    // （进度刚走到一大半，右边界是一条切面，不能带弧度）。
+    // 早先用 rect + rx 裁，四个角都是圆的 ⇒ 右端被裁成弧形，看着像走满了。
+    h('clipPath', { id: clipId }, h('path', { d: fill.d }))), h('path', { d: track.d, fill: track.fill }), h('path', { d: fill.d, fill: fill.fill }), h('g', { clipPath: `url(#${clipId})` }, h('g', { className: 'dshpc-loader-bar__stripe' }, 
+    // 三份：原图 + 左移一个周期 + 左移两个周期。
+    // 左端圆弧区也要铺满条纹，并且平移过程中左边界不露空。
+    ...[0, 1, 2].map((step) => h('g', {
+        key: step,
+        transform: step === 0 ? undefined : `translate(${String(-STRIPE_PERIOD * step)} 0)`,
+    }, h('path', { d: stripe.d, fill: stripe.fill }))))));
+}
+//# sourceMappingURL=LoaderBar.js.map

package/dist/ui/feedback/LoaderBar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoaderBar.js","sourceRoot":"","sources":["../../../src/ui/feedback/LoaderBar.ts"],"names":[],"mappings":"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"}

package/dist/ui/feedback/Loading.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 全局浮动 Loading 指示器（UI 基础层 · P1）。
+ *
+ * @deprecated 这是「自带定位 + 自带 pill 背景」的复合件，不属于通用加载图标。
+ *   只要图标请用 {@link Loader}（无背景、无定位，背景与位置归调用方）；
+ *   要居中 / 带文案的整卡请继续用 {@link LoadingToast} / {@link LoadingBlock}。
+ *   本组件保留不删（消费方可能还在用），但新代码不要再用。
+ *
+ * 用法：
+ *   <Loading />
+ *
+ * 行为：
+ * - fixed 定位在主内容容器右下角，**不占布局空间**；
+ * - 右侧贴齐主内容容器右边缘（`anchorId` 默认 `dshpc-main`），底部留 16px；
+ * - **三个小方块依次脉动，无任何文案**（基础抽象统一外观，禁止加字；用户 2026-10-06）；
+ * - 监听窗口 resize / scroll / 内容盒 resize，自动跟住内容宽度。
+ *
+ * 配套 also 导出 `<RunningBlocks />`：同样的三个脉动方块（无文案），
+ * 用于表格单元格里的「运行中」状态指示。
+ *
+ * 文档登记：docs/design/ui-foundation.md §二「唯一实现表」。
+ */
+import { createElement as h } from 'react';
+import { type Translate } from '../../utils/i18n.js';
+import { type LoadingHandle, type LoadingPosition, type LoadingVariant } from './loading-host.js';
+export interface LoadingProps {
+    /** 主内容容器 id，loading 贴到它的右下角；默认 `dshpc-main`。 */
+    anchorId?: string;
+}
+/** 浮动 Loading pill：三个脉动方块（无文案；基础抽象统一外观）。 */
+export declare function Loading(props: LoadingProps): ReturnType<typeof h>;
+/** 运行中状态用的三个脉动方块（无文案），颜色跟随 `currentColor`。 */
+export declare function RunningBlocks(): ReturnType<typeof h>;
+/** 两种加载提示共用的 props。 */
+export interface LoadingViewProps {
+    /** 文案，默认内置字典 `loadingDefault`（数据加载中 / Loading）。 */
+    text?: string;
+    /** 文案翻译函数，默认用内置字典。 */
+    translate?: Translate;
+}
+export interface LoadingOptions extends LoadingViewProps {
+    /** `toast` = 横排卡（默认）；`block` = 方块卡。 */
+    variant?: LoadingVariant;
+    /** 屏幕方位，默认 `bottom-center`（与 Toast 同屏位）；`center` 为正中。 */
+    position?: LoadingPosition;
+    /** 铺全屏遮罩挡住后面的一切点击，默认 false（不挡，随点随走）。 */
+    mask?: boolean;
+    /** 遮罩浓度 0–1，默认 0（全透明，但仍挡住点击）。 */
+    maskOpacity?: number;
+}
+/** 样式一：横排提示卡（转圈在左、文字在右），灰色底与 notify 的 info 卡同色。就地渲染，位置随调用方。 */
+export declare function LoadingToast(props: LoadingViewProps): ReturnType<typeof h>;
+/** 样式二：方块卡（转圈在上、文字在下，内距更大）。就地渲染，位置随调用方。 */
+export declare function LoadingBlock(props: LoadingViewProps): ReturnType<typeof h>;
+/**
+ * 命令式加载提示（全局唯一浮层，**不自动消失**）。所有插件、所有位置调用都落在**同一处**
+ * （默认屏幕下方居中，与 Toast 同屏位），且屏幕上永远只有一张卡 —— 后一次调用直接顶掉
+ * 前一次，被顶掉那次的句柄再 `close()` 是空操作。收起只能靠自己调 `close()`。
+ *
+ * ```ts
+ * const loading = showLoading({ text: '正在保存…', mask: true, maskOpacity: 0.3 })
+ * await save()
+ * loading.close()
+ * ```
+ *
+ * 无 `document` 时静默返回空句柄（Node 单测 / SSR 不炸）。
+ */
+export declare function showLoading(opts?: LoadingOptions): LoadingHandle;
+//# sourceMappingURL=Loading.d.ts.map

package/dist/ui/feedback/Loading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Loading.d.ts","sourceRoot":"","sources":["../../../src/ui/feedback/Loading.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,aAAa,IAAI,CAAC,EAAuB,MAAM,OAAO,CAAA;AAE/D,OAAO,EAAK,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAIL,KAAK,aAAa,EAElB,KAAK,eAAe,EAEpB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAA;AA6C1B,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,4CAA4C;AAC5C,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAOjE;AAED,8CAA8C;AAC9C,wBAAgB,aAAa,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC,CAGpD;AAMD,uBAAuB;AACvB,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sBAAsB;IACtB,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,uCAAuC;IACvC,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,eAAe,CAAA;IAC1B,wCAAwC;IACxC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAMD,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAQ1E;AAED,2CAA2C;AAC3C,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAQ1E;AAyDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,aAAa,CAUhE"}

package/dist/ui/feedback/Loading.js

@@ -0,0 +1,164 @@
+/**
+ * 全局浮动 Loading 指示器（UI 基础层 · P1）。
+ *
+ * @deprecated 这是「自带定位 + 自带 pill 背景」的复合件，不属于通用加载图标。
+ *   只要图标请用 {@link Loader}（无背景、无定位，背景与位置归调用方）；
+ *   要居中 / 带文案的整卡请继续用 {@link LoadingToast} / {@link LoadingBlock}。
+ *   本组件保留不删（消费方可能还在用），但新代码不要再用。
+ *
+ * 用法：
+ *   <Loading />
+ *
+ * 行为：
+ * - fixed 定位在主内容容器右下角，**不占布局空间**；
+ * - 右侧贴齐主内容容器右边缘（`anchorId` 默认 `dshpc-main`），底部留 16px；
+ * - **三个小方块依次脉动，无任何文案**（基础抽象统一外观，禁止加字；用户 2026-10-06）；
+ * - 监听窗口 resize / scroll / 内容盒 resize，自动跟住内容宽度。
+ *
+ * 配套 also 导出 `<RunningBlocks />`：同样的三个脉动方块（无文案），
+ * 用于表格单元格里的「运行中」状态指示。
+ *
+ * 文档登记：docs/design/ui-foundation.md §二「唯一实现表」。
+ */
+import { createElement as h, useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { t } from '../../utils/i18n.js';
+import { claimLoadingHost, createLoadingSlot, loadingOverlayClass, } from './loading-host.js';
+import { ensureComponentStyles, getStyleKit } from '../infra/css.js';
+import { LOADING_CSS } from '../infra/controls-css.js';
+import { Loader } from './Loader.js';
+const pillStyle = {
+    position: 'fixed',
+    bottom: '16px',
+    zIndex: 'var(--dshpc-z-dock)',
+    display: 'inline-flex', alignItems: 'center', gap: '6px',
+    padding: '5px 10px', borderRadius: 'var(--dshpc-radius-md)',
+    background: 'var(--dshpc-surface-1)', border: '1px solid var(--dshpc-border)',
+    boxShadow: 'var(--dshpc-shadow-1, 0 2px 8px rgba(0,0,0,.12))',
+    color: 'var(--dshpc-fg-2)', fontSize: 'var(--dshpc-font-xs)', lineHeight: 'var(--dshpc-line-sm)',
+    // 纯提示，不吃鼠标事件（别挡住底下的内容）。
+    pointerEvents: 'none',
+};
+const RIGHT_MARGIN_PX = 0;
+function useContentRight(anchorId) {
+    const [right, setRight] = useState(`${RIGHT_MARGIN_PX}px`);
+    useEffect(() => {
+        const update = () => {
+            const el = document.getElementById(anchorId);
+            if (!el)
+                return;
+            const rect = el.getBoundingClientRect();
+            const viewportW = document.documentElement.clientWidth;
+            setRight(`${Math.max(0, viewportW - rect.right + RIGHT_MARGIN_PX)}px`);
+        };
+        update();
+        window.addEventListener('resize', update);
+        window.addEventListener('scroll', update, true);
+        const ro = new ResizeObserver(update);
+        const el = document.getElementById(anchorId);
+        if (el)
+            ro.observe(el);
+        return () => {
+            window.removeEventListener('resize', update);
+            window.removeEventListener('scroll', update, true);
+            ro.disconnect();
+        };
+    }, [anchorId]);
+    return right;
+}
+/** 浮动 Loading pill：三个脉动方块（无文案；基础抽象统一外观）。 */
+export function Loading(props) {
+    ensureComponentStyles('loading', LOADING_CSS);
+    ensureComponentStyles('loading', LOADING_CSS);
+    const right = useContentRight(props.anchorId ?? 'dshpc-main');
+    return h('div', { style: { ...pillStyle, right }, role: 'status', 'aria-live': 'polite' }, h('span', { className: 'dshpc-run-blocks' }, h('i', null), h('i', null), h('i', null)));
+}
+/** 运行中状态用的三个脉动方块（无文案），颜色跟随 `currentColor`。 */
+export function RunningBlocks() {
+    ensureComponentStyles('loading', LOADING_CSS);
+    return h('span', { className: 'dshpc-run-blocks' }, h('i', null), h('i', null), h('i', null));
+}
+function textOf(props) {
+    return props.text ?? (props.translate ?? t)('loadingDefault');
+}
+/** 样式一：横排提示卡（转圈在左、文字在右），灰色底与 notify 的 info 卡同色。就地渲染，位置随调用方。 */
+export function LoadingToast(props) {
+    ensureComponentStyles('loading', LOADING_CSS);
+    return h('div', { className: 'dshpc-loading-toast', role: 'status', 'aria-live': 'polite' }, h(Loader, { size: 'sm' }), h('span', null, textOf(props)));
+}
+/** 样式二：方块卡（转圈在上、文字在下，内距更大）。就地渲染，位置随调用方。 */
+export function LoadingBlock(props) {
+    ensureComponentStyles('loading', LOADING_CSS);
+    return h('div', { className: 'dshpc-loading-block', role: 'status', 'aria-live': 'polite' }, h(Loader, { size: 'md' }), h('span', null, textOf(props)));
+}
+// 宿主实现：唯一浮层根 + 唯一槽位（`createLoadingSlot`）。屏幕上永远最多一张卡。
+function createLoadingHost() {
+    const slot = createLoadingSlot();
+    let root = null;
+    let container = null;
+    function flush() {
+        const state = slot.current();
+        if (state === null) {
+            root?.unmount();
+            container?.remove();
+            root = null;
+            container = null;
+            return;
+        }
+        if (root === null) {
+            container = document.createElement('div');
+            container.setAttribute('data-dshpc-loading-host', '');
+            document.body.appendChild(container);
+            root = createRoot(container);
+        }
+        ensureComponentStyles('loading', LOADING_CSS, getStyleKit());
+        const { request } = state;
+        const opacity = Math.min(1, Math.max(0, request.maskOpacity));
+        root.render(h('div', { className: loadingOverlayClass(request.position) }, request.mask
+            ? h('div', {
+                className: 'dshpc-loading-overlay__mask',
+                style: { background: `rgba(0, 0, 0, ${opacity})` },
+            })
+            : null, request.variant === 'block'
+            ? h(LoadingBlock, { text: request.text, translate: request.translate })
+            : h(LoadingToast, { text: request.text, translate: request.translate })));
+    }
+    return {
+        show(request) {
+            const handle = slot.show(request);
+            flush();
+            return {
+                close() {
+                    handle.close();
+                    flush();
+                },
+            };
+        },
+    };
+}
+/**
+ * 命令式加载提示（全局唯一浮层，**不自动消失**）。所有插件、所有位置调用都落在**同一处**
+ * （默认屏幕下方居中，与 Toast 同屏位），且屏幕上永远只有一张卡 —— 后一次调用直接顶掉
+ * 前一次，被顶掉那次的句柄再 `close()` 是空操作。收起只能靠自己调 `close()`。
+ *
+ * ```ts
+ * const loading = showLoading({ text: '正在保存…', mask: true, maskOpacity: 0.3 })
+ * await save()
+ * loading.close()
+ * ```
+ *
+ * 无 `document` 时静默返回空句柄（Node 单测 / SSR 不炸）。
+ */
+export function showLoading(opts) {
+    if (typeof document === 'undefined')
+        return { close: () => { } };
+    return claimLoadingHost(createLoadingHost).show({
+        text: opts?.text,
+        variant: opts?.variant ?? 'toast',
+        position: opts?.position ?? 'bottom-center',
+        mask: opts?.mask === true,
+        maskOpacity: opts?.maskOpacity ?? 0,
+        translate: opts?.translate,
+    });
+}
+//# sourceMappingURL=Loading.js.map

package/dist/ui/feedback/Loading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Loading.js","sourceRoot":"","sources":["../../../src/ui/feedback/Loading.ts"],"names":[],"mappings":"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"}

package/dist/ui/feedback/Modal.d.ts

@@ -0,0 +1,73 @@
+import { createElement as h, type ReactNode } from 'react';
+import { type Translate } from '../../utils/i18n.js';
+/** 弹窗尺寸档：sm≈确认框 / md(默认) / lg 大窗。 */
+export type ModalSize = 'sm' | 'md' | 'lg';
+export interface ModalProps {
+    /** 头部左侧图标位（可不传）。 */
+    icon?: ReactNode;
+    title?: ReactNode;
+    /**
+     * 标题**下方**的副标题行（等宽小字；会话预览的 sessionId 就放这里 —— 用户 2026-10-22：
+     * 标识属于标题区，不占正文）。与标题同宽、可换行。
+     */
+    subtitle?: ReactNode;
+    /** 标题右侧小块：数字 / 标签（ReactNode；demo 用 Chip 演示）。 */
+    headerExtra?: ReactNode;
+    /** 头部右侧动作区：关闭钮之外的更多按钮（ReactNode）。 */
+    headerActions?: ReactNode;
+    /** 关闭回调；不传则 ✕ 不显示（必须自己给关闭路径）。 */
+    onClose?: () => void;
+    /** 是否显示右上角 ✕（默认 = `onClose` 是否传入）。确认框传 false 即可去掉小叉。 */
+    closable?: boolean;
+    /** 点遮罩是否关闭（默认 true；误触代价大的场景设 false）。 */
+    closeOnMask?: boolean;
+    /** 按 Esc 是否关闭（默认 true）。 */
+    escClose?: boolean;
+    /**
+     * 有异步在跑（如 footer 里的 `Button` 正在 loading）：为真时遮罩 / Esc / ✕ **三条关闭路径全失效**，
+     * 内容照常渲染。与 `closeOnMask` / `escClose` / `closable` 是"与"关系 —— 它是否决项，不替代它们。
+     */
+    busy?: boolean;
+    /**
+     * **锁死全部交互**（与 loading 解耦：按钮转不转圈是另一回事）。为真时：
+     *  · 面板内的核心控件各自按**自己的禁用态**渲染（灰掉、点不动、Tab 跳过）；
+     *  · 面板上盖一层**全透明**的点击层，消费方自绘的元素也跟着点不动，鼠标是禁止手势；
+     *  · 遮罩 / Esc / ✕ 三条关闭路径同时失效。
+     *
+     * 一律只做「或」，**永不写回调用方的 `disabled`**：本来禁用的解锁后照样禁用，锁定期间你把它改成
+     * 能用 / 禁用，解锁后也照你的。不压任何灰色遮罩 —— 整块蒙一层会让人以为界面坏了。
+     * 受控项，不落内部 state：关掉重开自然回到未锁。
+     */
+    locked?: boolean;
+    /** 尺寸档：sm=小确认框家族 / md·lg=大弹窗家族；也可用 width/height 精确覆盖。 */
+    size?: ModalSize;
+    /** 面板宽度（默认随 size：sm 360px / md 720px / lg 1120px，均带视口兜底）。 */
+    width?: string;
+    /** 面板高度（默认仅 lg 有：calc(100% - 80px)，同兄弟项目大弹窗）。 */
+    height?: string;
+    /** 面板最大宽度 / 最大高度覆盖（不传走 size 默认）。 */
+    maxWidth?: string;
+    maxHeight?: string;
+    /** 不渲染头部（沉浸式 / 无标题场景）。 */
+    hideHeader?: boolean;
+    footer?: ReactNode;
+    /**
+     * footer **左侧**的一行过程提示（换字即翻牌，太长省略、hover 跑马灯）。
+     * 不传 = 不占位、与以前完全一样；传了就自动出现（footer 也可不给，它会自己撑起底栏）。
+     * 换文案只改这个值，动效由 `FlipText` 负责。
+     */
+    notice?: string;
+    /** footer 上面那条分隔线（默认 true）。传 false 关闭；sm 确认框家族本来就没有。 */
+    footerDivider?: boolean;
+    /** 追加 class（只允许补布局 / 视觉修饰，不许覆盖皮肤）。 */
+    className?: string;
+    children?: ReactNode;
+    translate?: Translate;
+}
+/**
+ * 模态弹窗（自绘 overlay，**不用 react-dom 的 portal**，避免多一个必需依赖）。
+ *
+ * 定位：它是**呈现方式**，不是内容 —— 会话预览这类功能模块要用弹窗时用它来承载（需求文档 §4）。
+ */
+export declare function Modal(props: ModalProps): ReturnType<typeof h>;
+//# sourceMappingURL=Modal.d.ts.map

package/dist/ui/feedback/Modal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Modal.d.ts","sourceRoot":"","sources":["../../../src/ui/feedback/Modal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,IAAI,CAAC,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC1D,OAAO,EAAK,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAOvD,qCAAqC;AACrC,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAE1C,MAAM,WAAW,UAAU;IACzB,oBAAoB;IACpB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,gDAAgD;IAChD,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,qCAAqC;IACrC,aAAa,CAAC,EAAE,SAAS,CAAA;IACzB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,wCAAwC;IACxC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,yDAAyD;IACzD,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0BAA0B;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAwF7D"}

package/dist/ui/feedback/Modal.js

@@ -0,0 +1,83 @@
+import { createElement as h } from 'react';
+import { t } from '../../utils/i18n.js';
+import { ensureComponentStyles } from '../infra/css.js';
+import { FEEDBACK_CSS } from './feedback-css.js';
+import { OverlayHead, OverlayLockCatcher, OverlayLockedProvider, OverlayMask, useEscapeClose, useLockGuards } from '../infra/overlay.js';
+import { PanelSurface } from '../infra/panel.js';
+import { FlipText } from '../display/FlipText.js';
+/**
+ * 模态弹窗（自绘 overlay，**不用 react-dom 的 portal**，避免多一个必需依赖）。
+ *
+ * 定位：它是**呈现方式**，不是内容 —— 会话预览这类功能模块要用弹窗时用它来承载（需求文档 §4）。
+ */
+export function Modal(props) {
+    ensureComponentStyles('feedback', FEEDBACK_CSS);
+    const tt = props.translate ?? t;
+    // busy / locked 都是否决项：三条关闭路径一起封死（✕ 见下面 showClose）。
+    // locked 比 busy 多管一层：面板整块不可交互（inert）。
+    const busy = props.busy === true;
+    const locked = props.locked === true;
+    const denyClose = busy || locked;
+    const closeOnMask = !denyClose && props.closeOnMask !== false;
+    useEscapeClose(!denyClose && props.escClose !== false, denyClose ? undefined : props.onClose);
+    useLockGuards(locked);
+    // 空串等同于没给：底栏那块地方复用给下一轮时，传 "" 就把上一句清干净、不留占位。
+    const notice = props.notice === '' ? undefined : props.notice;
+    // 默认宽高（兄弟项目真值：小框 360px（task-list.tsx:457）/ 大弹窗 min(1120px,100vw-32px) × calc(100%-80px)（archive-session-css.ts:42））。
+    // 宽度用 `100%`（相对遮罩盒）而不是 `100vw`：遮罩已按右侧分栏让位（见 feedback.css），
+    // 用 `100vw` 算出来的宽在分栏在场时会溢出到分栏上，等于白让（用户 2026-10-22）。
+    const sizeStyle = {
+        sm: { width: '360px', maxWidth: 'calc(100% - 48px)' },
+        md: { width: 'min(720px, calc(100% - 32px))', maxHeight: '86vh' },
+        lg: { width: 'min(1120px, calc(100% - 32px))', height: 'calc(100% - 80px)' },
+    };
+    const s = sizeStyle[props.size ?? 'md'];
+    const showClose = props.closable !== false && props.onClose !== undefined && !denyClose;
+    const showHeader = props.hideHeader !== true &&
+        (props.icon !== undefined ||
+            props.title !== undefined ||
+            props.subtitle !== undefined ||
+            props.headerExtra !== undefined ||
+            props.headerActions !== undefined ||
+            showClose);
+    return h(OverlayMask, {
+        kind: 'center',
+        closeOnMask,
+        onClose: denyClose ? undefined : props.onClose,
+        // inert 子树不参与命中测试，鼠标落到遮罩上 —— 禁止手势得挂在遮罩这层才看得见。
+        attrs: locked ? { 'data-dshpc-locked': '' } : undefined,
+    }, h(OverlayLockedProvider, { value: locked }, 
+    // 表面（底色/描边/圆角/阴影）来自 panel.css 的 modal 档；`.dshpc-modal` 只剩家族布局，
+    // 且继续作为既有类名别名存在（消费方写在它上面的覆盖不受影响）。
+    h(PanelSurface, {
+        tier: 'modal',
+        className: `dshpc-modal${props.size ? ` dshpc-modal--${props.size}` : ''}${locked ? ' dshpc-modal--locked dshpc-locked' : ''}${props.className !== undefined && props.className !== '' ? ` ${props.className}` : ''}`,
+        style: {
+            width: props.width ?? s.width,
+            maxWidth: props.maxWidth ?? s.maxWidth,
+            maxHeight: props.maxHeight ?? s.maxHeight,
+            height: props.height ?? s.height,
+        },
+        stopPropagation: true,
+    }, 
+    // 头部与遮罩都是浮层公共件（overlay.ts），SideSheet 用的是同一套。
+    showHeader
+        ? h(OverlayHead, {
+            icon: props.icon,
+            title: props.title,
+            subtitle: props.subtitle,
+            extra: props.headerExtra,
+            actions: props.headerActions,
+            closeLabel: tt('modalClose'),
+            onClose: showClose ? props.onClose : undefined,
+        })
+        : null, 
+    // body 是**唯一滚动容器**：内距归它、滚动条归它、滚动条贴面板右缘；
+    // 内容只管按流排，不许自己定高、不许自己再开滚动条（用户 2026-10-22 定的口径）。
+    h('div', { className: 'dshpc-modal__body' }, props.children ?? null), props.footer === undefined && notice === undefined
+        ? null
+        : h('div', { className: `dshpc-modal__foot${props.footerDivider === false ? ' dshpc-modal__foot--bare' : ''}` }, notice === undefined ? null : h(FlipText, { text: notice, className: 'dshpc-modal__notice', sweep: true }), props.footer), 
+    // 透明点击层兜住消费方自绘的元素；核心控件此时已各自是真 disabled。
+    locked ? h(OverlayLockCatcher) : null)));
+}
+//# sourceMappingURL=Modal.js.map

package/dist/ui/feedback/Modal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Modal.js","sourceRoot":"","sources":["../../../src/ui/feedback/Modal.ts"],"names":[],"mappings":"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"}

package/dist/ui/feedback/SideSheet.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 侧边抽屉（SideSheet）—— 从屏幕左/右缘滑入的**覆盖式**浮层。
+ *
+ * 与 PanelDock 的关系（用户 2026-11-02 定）：**皮肤一模一样**（同一份 side-panel.css：
+ * 头部、拖拽条、关闭钮、背景阴影、入场动画），宽度也能拖；差别只有两点：
+ *   · PanelDock 是布局成员（sticky 占宽、挤窄主区，调用方必须给挂载点）；
+ *   · SideSheet 是浮层（absolute 贴边、盖住页面，自铺遮罩，不需要挂载点）；
+ *   · SideSheet **没有收起**（没有耳朵、没有收起钮）—— 关就是关。
+ *
+ * 开关行为与 Modal 一致：渲染即显示（`{open && <SideSheet … />}`）、点遮罩 / Esc / ✕ 都能关，
+ * 三者都可关掉；遮罩与 Esc 判定走 overlay.ts 的公共件。
+ */
+import { type ReactNode } from 'react';
+import { type Translate } from '../../utils/i18n.js';
+/** 从哪一侧滑入。默认 `left`。 */
+export type SideSheetSide = 'left' | 'right';
+export interface SideSheetProps {
+    /** 贴哪条边、从哪边滑入（默认 `left`）。 */
+    side?: SideSheetSide;
+    /** 内置头的标题。 */
+    title?: ReactNode;
+    /** 标题前的图标位。 */
+    icon?: ReactNode;
+    /** 标题**右侧**的任意内容（按钮、标签、下拉……）。 */
+    extra?: ReactNode;
+    /**
+     * 整块替换头部：
+     *   · 不传 ⇒ 内置头（`icon` + `title` + `extra`）
+     *   · `null` ⇒ 不要头部（关闭钮自动浮到右上角）
+     *   · 其他 ReactNode ⇒ 你的头部，库不加内边距/边框/背景
+     */
+    header?: ReactNode | null;
+    /** 是否显示关闭钮（默认 true）。 */
+    closable?: boolean;
+    /** 自定义关闭图标（默认 ✕）。 */
+    closeIcon?: ReactNode;
+    /** 关闭回调；不传则不出关闭钮（必须自己给关闭路径）。 */
+    onClose?: () => void;
+    /**
+     * 受控开关（默认 true）。传 `false` 时先播收起动画再卸载 —— 想让关闭有动效就常驻渲染它、只切这个布尔；
+     * 继续用 `{open && <SideSheet/>}` 的老写法也能跑，只是没有收起动画（一卸载就没 DOM 了）。
+     */
+    open?: boolean;
+    /** 点遮罩是否关闭（默认 true）。 */
+    closeOnMask?: boolean;
+    /** 按 Esc 是否关闭（默认 true）。 */
+    escClose?: boolean;
+    /**
+     * 有异步在跑（如 footer 里的 `Button` 正在 loading）：为真时遮罩 / Esc / ✕ **三条关闭路径全失效**，
+     * 内容照常渲染。与 `closeOnMask` / `escClose` / `closable` 是"与"关系 —— 它是否决项，不替代它们。
+     */
+    busy?: boolean;
+    /** 锁死全部交互（含义见 `Modal.locked`）：抽屉整块点不动、Tab 进不去、三条关闭路径同时失效。 */
+    locked?: boolean;
+    /** **初始**宽度（px，默认 460，与 PanelDock 同档）；拖过之后以拖出来的为准。 */
+    width?: number;
+    /** 可拖宽的下限（默认 320）。 */
+    minWidth?: number;
+    /** 可拖宽的上限；不传 = 只受遮罩盒宽度约束。 */
+    maxWidth?: number;
+    /** 能否拖宽（默认 true）。 */
+    resizable?: boolean;
+    footer?: ReactNode;
+    /** 底栏左侧的一行过程提示（换字即翻牌，超长省略 + hover 跑马灯）。不传 = 不占位。 */
+    notice?: string;
+    children?: ReactNode;
+    translate?: Translate;
+}
+export declare function SideSheet(props: SideSheetProps): ReactNode;
+//# sourceMappingURL=SideSheet.d.ts.map

package/dist/ui/feedback/SideSheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SideSheet.d.ts","sourceRoot":"","sources":["../../../src/ui/feedback/SideSheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAmD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AACvF,OAAO,EAAK,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAQvD,wBAAwB;AACxB,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAA;AAE5C,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,cAAc;IACd,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,eAAe;IACf,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,iCAAiC;IACjC,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IACzB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,qBAAqB;IACrB,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,wBAAwB;IACxB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qBAAqB;IACrB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CA8I1D"}