dsh-plugin-core 0.24.0 → 0.26.0

package/docs/help/ui.md

@@ -4,7 +4,7 @@
 
 > EN: ui — base controls
 
-导出：Button、IconButton、Segmented、SplitGroup、Input、PrefixedInput、NumberInput、Textarea、Checkbox、fieldMetricsOf、Picker、WorkspacePicker、ModelPicker、DateTimePicker、Surface、Card、StripCard、Chip、Table、Pagination、Modal、SideSheet、FieldHint、setTooltipRenderer、showToast、notify、showHostToast、Loader、LoaderBar、Loading、RunningBlocks、SectionHead、MarqueeText、LiveText、QuickToolbar、startResizeLayoutWidth、PanelDock、createPanelDock、DockPanel、ensureControls、setStyleKit
+导出：Button、IconButton、Segmented、SplitGroup、Input、PrefixedInput、NumberInput、Textarea、Checkbox、fieldMetricsOf、Picker、WorkspacePicker、ModelPicker、DateTimePicker、Surface、Card、StripCard、Chip、Table、Pagination、Modal、SideSheet、FieldHint、setTooltipRenderer、showToast、notify、showHostToast、Loader、LoaderBar、Loading、RunningBlocks、SectionHead、MarqueeText、FlipText、LiveText、QuickToolbar、startResizeLayoutWidth、PanelDock、createPanelDock、DockPanel、ensureControls、setStyleKit
 
 ## 概览
 
@@ -397,6 +397,44 @@ h(StripCard, {
 | `className` | `string` | — | 追加 class（只允许补布局，不许覆盖皮肤） | Extra class (layout only, never overrides the skin) |
 | `children` | `ReactNode` | — | 标签内容（maxWidth + 纯文字时自动接跑马灯） | Tag content (auto-marqueed when maxWidth + plain text) |
 
+## FlipText（翻牌文本）
+
+> EN: FlipText
+
+一行文字，换一句翻一次牌：旧的上移出、新的从下进。**只给文本，动效自己放** —— `text` 变了就翻，没变不动（同一句重复设置不重播）。**空串 = 没有文案**：不渲染、不占位，同一块地方复用时靠它把上一句清干净；清空后再给值是直接出现，不从下方翻上来。
+
+> EN: One line of text that flips on every change: the old line slides up and out, the new one comes in from below. **Give it text; it owns the motion** — a changed `text` flips, an unchanged one does nothing (setting the same line twice does not replay). **An empty string means no line at all**: nothing rendered, no space taken, which is how a reused spot gets cleared; the next value then appears outright instead of sliding in.
+
+溢出与 MarqueeText 同一套：单行、放不下三点省略，鼠标移上去跑马灯（复用同一个实现，不重复测宽）。高度恒为一行，永不换行。
+
+> EN: Overflow behaves exactly like MarqueeText: one line, an ellipsis when it does not fit, marquee on hover (same implementation, no second width measurement). Height stays at one line and it never wraps.
+
+宽度三档同 Button / Chip：`width` 优先，`width` 未设时 `minWidth` / `maxWidth` 生效；三者都不传 = 随父容器（flex 子项自然伸缩，弹窗底栏就是这么用的）。要放进弹窗底栏左侧**不要自己包**，直接用 `Modal` / `ConfirmModal` / `AlertModal` / `SideSheet` 的 `notice`。
+
+> EN: Widths follow Button / Chip: `width` wins; `minWidth` / `maxWidth` apply only when it is unset; none of the three means "follow the parent" (a flex child stretches naturally — that is how the dialog footer uses it). To put it on the left of a dialog footer, use the `notice` prop on `Modal` / `ConfirmModal` / `AlertModal` / `SideSheet` rather than wrapping it yourself.
+
+| 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
+|---|---|---|---|---|
+| `text` | `string` | —（必填） | 当前文本；变了就翻一次牌。**空串 = 没有文案**：不渲染、不占位（同一块地方复用靠它清场）；清空后再给值是直接出现，不从下方翻上来 | Current text; a change flips it once. **An empty string means no line at all**: nothing rendered, no space taken (that is how a reused spot is cleared); the next value appears outright instead of sliding in |
+| `width` | `number \| string` | — | 固定宽（px 或任意 CSS 宽度）；与 minWidth / maxWidth 互斥，一旦设定后两者自动失效 | Fixed width (px or any CSS width); mutually exclusive with minWidth/maxWidth — once set, the other two are ignored |
+| `minWidth` | `number \| string` | — | 最小宽：width 未设时生效 | Minimum width: applies only when width is unset |
+| `maxWidth` | `number \| string` | — | 最大宽：width 未设时生效，文字超出折叠成省略号，hover 以跑马灯展开 | Maximum width: applies only when width is unset; overflowing text collapses to an ellipsis and marquees on hover |
+| `className` | `string` | — | 追加 class（只补字体 / 颜色这类皮肤，布局归组件自己） | Extra class (font / colour skin only; layout belongs to the component) |
+
+```tsx id="ui-flip-text-example"
+import { FlipText } from 'dsh-plugin-core/ui'
+
+// 换文案 = 改 text，动效自己放（旧的上移出、新的从下进）
+const [step, setStep] = useState('正在扫描工作区…')
+h(FlipText, { text: step })
+
+// 溢出：放不下三点省略，hover 跑马灯
+h(FlipText, { text: step, maxWidth: 220 })
+
+// 宽度三档：width 优先，其次 minWidth / maxWidth
+h(FlipText, { text: step, width: 200 })
+```
+
 ## Table（表格）
 
 > EN: Table
@@ -681,6 +719,7 @@ Modal 是自绘 overlay，不走 react-dom portal。
 | `maxWidth` | `string` | 按 size | 任意 CSS 值，覆盖 size 的宽度上限；不要用 vw（遮罩已按右侧分栏让位） | Any CSS value, overriding the size’s max width; avoid vw (the mask already yielded to the right column) |
 | `hideHeader` | `boolean` | 'false' | 不渲染头部（沉浸式） | Skip header (immersive) |
 | `footer` | `ReactNode` | — | 底栏（按钮区；上下内距相等、内容垂直居中） | Footer (button area; symmetric padding, vertically centred) |
+| `notice` | `string` | — | 底栏**左侧**的一行过程提示：换文案即翻牌，超长省略 + hover 跑马灯。不传 = 不占位、与以前完全一样；**传空字符串 = 清场**；footer 也可不给（它会自己撑起底栏） | One-line progress notice on the **left** of the footer: changing the string flips it, overflow elides and marquees on hover. Omitted = nothing at all (unchanged behaviour); **an empty string clears it**; `footer` may be omitted too — the notice alone brings the footer up |
 | `footerDivider` | `boolean` | 'true' | 底栏上面的那条分隔线；传 false 关掉（sm 确认框本来就没有） | The divider above the footer; pass false to drop it (sm dialogs never have one) |
 | `className` | `string` | — | 追加 class（只补布局 / 视觉修饰，别覆盖皮肤） | Extra class (layout / visual tweaks only; do not override the skin) |
 | `children` | `ReactNode` | — | 主体 | Body |
@@ -694,6 +733,7 @@ Modal 是自绘 overlay，不走 react-dom portal。
 | `loadingText` | `boolean` | true | 传 false：loading 时两颗钮清文案、锁住有文案的宽度、只留居中的圈（见 `Button.loadingText`） | Pass false: while loading, both buttons drop their labels, freeze at the labelled width and show a centred spinner (see `Button.loadingText`) |
 | `onConfirm / onCancel` | `() => unknown` | — | 确认 / 取消回调；返回 Promise 时按钮转圈、整框锁死，settle 后恢复；返回 `false` 不关 | Confirm / cancel callback; a Promise makes its button spin and locks the dialog until it settles; `false` keeps it open |
 | `confirmLoading / cancelLoading` | `boolean` | false | 外部驱动对应按钮 loading，与按钮自身异步状态取或 | External loading for that button, OR-ed with its own async state |
+| `notice` | `string` | — | 底栏**左侧**的一行过程提示（loading 期间逐步换文案、换一句翻一次牌，超长省略 + hover 跑马灯）。不传 = 不占位；**传空字符串 = 清场**（同一块地方复用下一轮时用它把上一句清掉） | One-line progress notice on the **left** of the footer (swap the string while loading, each change flips; overflow elides and marquees on hover). Omitted = nothing at all; **an empty string clears it** (use it when the same spot is reused for the next round) |
 | `closeOnMask` | `boolean` | 'true' | 点遮罩关闭（等于取消） | Close on mask click (treated as cancel) |
 | `size` | `ModalSize` | 'sm' | 尺寸档 | Size tier |
 | `translate` | `Translate` | 内置字典 | 覆盖确定 / 取消文案 | Override confirm / cancel copy |
@@ -707,6 +747,7 @@ Modal 是自绘 overlay，不走 react-dom portal。
 | `loadingText` | `boolean` | true | 传 false：loading 时清文案、锁住有文案的宽度、只留居中的圈（见 `Button.loadingText`） | Pass false: while loading, drop the label, freeze at the labelled width and show a centred spinner (see `Button.loadingText`) |
 | `onConfirm` | `() => unknown` | — | 确认 / 遮罩 / Esc 的统一出口；返回 Promise 时转圈锁框，返回 `false` 不关 | Single exit for confirm / mask / Esc; a Promise spins and locks it, `false` keeps it open |
 | `confirmLoading` | `boolean` | false | 外部驱动按钮 loading，与按钮自身异步状态取或 | External button loading, OR-ed with its own async state |
+| `notice` | `string` | — | 底栏**左侧**的一行过程提示（loading 期间逐步换文案、换一句翻一次牌，超长省略 + hover 跑马灯）。不传 = 不占位；**传空字符串 = 清场**（同一块地方复用下一轮时用它把上一句清掉） | One-line progress notice on the **left** of the footer (swap the string while loading, each change flips; overflow elides and marquees on hover). Omitted = nothing at all; **an empty string clears it** (use it when the same spot is reused for the next round) |
 | `closeOnMask` | `boolean` | 'true' | 点遮罩关闭 | Close on mask click |
 | `size` | `ModalSize` | 'sm' | 尺寸档 | Size tier |
 | `translate` | `Translate` | 内置字典 | 覆盖按钮文案 | Override the button copy |
@@ -749,6 +790,7 @@ Modal 是自绘 overlay，不走 react-dom portal。
 | `width / minWidth / maxWidth` | `number / number / number` | 460 / 320 / — | 初始宽度 / 拖拽下限 / 拖拽上限（px；上限缺省 = 遮罩盒宽） | Initial width / resize floor / resize ceiling (px; ceiling defaults to the mask box) |
 | `resizable` | `boolean` | true | 能否拖宽（关掉就没有拖拽条） | Whether it resizes by dragging (off = no handle) |
 | `footer / children` | `ReactNode / ReactNode` | — / — | 底栏 / 主体（主体是唯一滚动容器） | Footer / body (the body is the only scroll container) |
+| `notice` | `string` | — | 底栏**左侧**的一行过程提示（换文案即翻牌，超长省略 + hover 跑马灯）。不传 = 不占位；**传空字符串 = 清场**（抽屉常驻渲染，关掉再开时用它清上一轮） | One-line progress notice on the **left** of the footer (changing it flips; overflow elides and marquees on hover). Omitted = nothing at all; **an empty string clears it** (the drawer stays mounted, so this is how the previous round is wiped) |
 | `translate` | `Translate` | 内置字典 | 覆盖关闭 / 拖拽条的文案 | Override close / resize copy |
 
 ```tsx id="ui-sidesheet-example"

package/docs/requirements.md

@@ -46,7 +46,7 @@ dsh-plugin-core/
 ### 2.2 ui
 
 - 零件：Button / Input 家族 / Textarea / Checkbox / Segmented / 下拉框 / 搜索框 / 滑轨 /
-  MarqueeText / LiveText / Field（含错误提示）/ resizer / DateTime / TimeRange
+  MarqueeText / FlipText / LiveText / Field（含错误提示）/ resizer / DateTime / TimeRange
 - 选择器：`Picker`（通用：单选/多选/上限/搜索/分组/空态/降级）、`ModelPicker`、
   `WorkspacePicker`（选工作区）；`FilePicker` 已删（2026-10-20 用户：文件选择框没有用）
 - 日期时间：`DateTimePicker`（2026-10-24 新增：单值 / 时间段 × 精度 day/hour/minute/second；
@@ -126,6 +126,15 @@ dsh-plugin-core/
     清文案后读屏名称靠 `aria-label`（字符串 children 自动补，复合 children 由调用方给）；
     首帧就是 loading（没有「有文案的宽度」可量）时锁不到宽，走 ① 的 `width`。
     loading 圈包进 `.dshpc-btn__icon`（svg 被 1em 规则接管）⇒ 有 icon 的按钮切 loading 宽度零差。
+  - **弹窗底栏左侧的过程提示**（2026-11-04 用户拍板）：`Modal` / `ConfirmModal` / `AlertModal` / `SideSheet`
+    各加一个 `notice?: string`，渲染在 footer 最左；**不传 = 不占位**，与接入前完全一样（`footer` 也可不给，
+    notice 自己撑起底栏）。换文案即翻牌（旧的上移出、新的从下进），单行、超长三点省略、hover 跑马灯 ——
+    跑马灯与省略**复用 `MarqueeText`**，不另写一份测宽；高度恒为一行，永不换行。
+    **空串 = 没有文案**（2026-11-04 用户补的要求）：不渲染、不占位 —— 底栏那块地方被下一轮复用时，
+    传空串就把上一句清干净；清空后第一次给值是直接出现、不从下方翻上来（没有上一句可翻）。
+    实现分两层（用户拍板「拆成两层、不做引擎、不监听 loading」）：控件 `FlipText`（`text` 变了就翻，
+    没变不动；宽度三档与 Button / Chip 同口径：`width` 优先，其次 `minWidth` / `maxWidth`，
+    全不传 = 随父容器）+ 弹窗只做「挂载位 + 透传」。步骤队列、loading 状态一律由调用方 setState 管。
   - `Loading` 是旧的「自带定位 + 自带 pill 背景」复合件，**保留不删**但标 `@deprecated`，新代码用 `Loader`。
 - 布局基础：`PanelDock` / `DockPanel` / `createPanelDock`（**可停靠分栏容器**：多面板并存、按组名寻址、拖拽拉栏、宽度记忆；2026-10-20 拍板用此名，替代早先的 `SidebarLayout` / `SplitPane`）。只做右侧；组名与窗口一对一；默认上限 3，超限拒绝新开；不做 tab 切换 / 自动淘汰 / 多份同名；**面板本身始终是布局成员，不做面板浮层**（2026-10-28 补：**收起** = 面板退出布局、另出右侧一只独立的 `position: fixed` 耳朵，点耳朵展开并还原宽度；关闭不留耳朵——耳朵是独立浮层，不是把面板变浮层）。**结构照成熟库口径写 children，`open/close` 只传 id，不把页面树塞进调用参数**
 - 浮动快捷工具栏：`QuickToolbar`（2026-10-31 用户拍板）：右侧一列独立圆钮，纵向**恒贴屏幕底边**（默认 16px）；横向默认贴屏幕右缘，传 `anchorId` / `anchor()` 时贴到指定控件右缘外侧，右侧放不下则退回屏幕右缘（控件找不到按跟随窗口处理）。内置回顶部默认 `when:'scroll'`、阈值 320，`backToTop:false` 可关掉，对象可调 `order` / `label` / `threshold`；自定义项 `items` 支持 `icon` / `label` / `onClick` / `visible` / `when` / `order` / `threshold` / `color` / `fgColor`，统一 `onAction`。旧的 `BackToTop` **全部删除**，只保留这一份，不做迁移。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-core",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "packageManager": "pnpm@12.3.4",
   "description": "Shared base for DSH plugins: design tokens, UI controls, utils, workspace explorer, session preview",
   "keywords": [