dsh-plugin-core 0.35.4 → 0.35.6

package/docs/help/ui.md

@@ -59,6 +59,10 @@ Segmented：`items`（必填）支持单选 / 多选，`size`（默认 lg；三
 
 > EN: Segmented: `items` (required) supports single or multiple selection; `size` (default lg; totals 24 / 28 / 32), `bordered` (1px outer frame, same total height), `multiple` (multi-select). One look only: grey track + white selected pill; its stroke ring and shadow come from the host elevation token (the offline fallback has no ring). The selected pill’s colors go through `tone` only: a built-in color name (business / success / warning / danger / purple / pink / cyan / teal / orange / indigo / rose / slate, same names as Chip) lets the core pick background and text per theme; `{ bg, fg }` uses that pair verbatim in both themes (contrast is the caller’s call). An item’s leading `icon` takes any node (official icon component, array, or custom); `label` also accepts a node; order is always icon → label → count. With only an icon (no label / count / badge) the segment squares itself (width = segment height), and the accessible name comes from `ariaLabel`, falling back to `tooltip`. An item’s `count` (muted text; auto-lightened to follow the selected pill’s text color while selected) and `badge` (red pill) take `number | string`: numbers ≤0 render nothing, strings render as given (e.g. `'1K'` / `'99+'`).
 
+多选（`multiple`）时每段的最小宽度等于该档段高：最窄也是正方形，文案更长则自然撑成横向长方形，不会出现宽比高还小的竖条；`weekday` 与只有图标的固定方块也由这条下限兜住。
+
+> EN: In `multiple` mode every segment has a minimum width equal to its own segment height: the narrowest case is a square, longer labels grow it into a landscape rectangle, and no segment is ever taller than it is wide. Fixed-width squares (`weekday`, icon-only) are clamped by this floor too.
+
 | 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
 |---|---|---|---|---|
 | `variant` | `上表 18 档（primary/secondary/danger/success/warning/info/outline/danger-outline/ghost/link + 扩展 purple/pink/cyan/teal/orange/indigo/rose/slate）` | 'outline' | 外观档 | Appearance tier |
@@ -365,9 +369,13 @@ h(Surface, { tone: 'sunken', border: 'dashed', padding: 'lg' }, '还没做的东
 
 > EN: The header centers vertically as a whole; drop a bare element into `action` and it centers. Colors come from tokens, so light/dark follows the host.
 
-`hoverable` 开启后**整卡**悬停变色、同时把光标改成 `pointer`，统一吃 `--dshpc-card-hover`（亮 7% 蓝 / 暗 13% 蓝），默认关；`filled` 切底色，默认有底（Card = surface-1，StripCard = accent 浅底），`false` 时底透明但边框仍在。两根轴都只改 `--surface-bg`，插件不用再自己写 `:hover` 规则；透明底 + hover 也照常变色。
+`hoverable` 开启后悬停变色、同时把光标改成 `pointer`，统一吃 `--dshpc-card-hover`（亮 7% 蓝 / 暗 13% 蓝），默认关；`filled` 切底色，默认有底（Card = surface-1，StripCard = accent 浅底），`false` 时底透明但边框仍在。两根轴都只改 `--surface-bg`，插件不用再自己写 `:hover` 规则。
+
+> EN: `hoverable` (default off) changes the fill on hover and switches the cursor to `pointer`, using `--dshpc-card-hover` (7% blue light / 13% blue dark). `filled` (default on) controls the background — Card uses surface-1, StripCard the accent tint; `false` makes it transparent but keeps the border. Both axes only rewrite `--surface-bg`, so plugins no longer need their own `:hover` rules.
+
+展开的卡片用 `hoverScope` 选作用域，默认 `'head'`：根节点零内距并统一裁圆角，`__body` 作为「上面那一整块」独立承担内距、边到边变色；展开态不改内距，上下两圈留白对称，两块之间的间隔也属于头部区、跟着一起变色；`__panel` 是它的兄弟节点，不铺背景、不参与 hover，鼠标在展开区里操作时整卡都不触发。StripCard 的通高色条相对根节点定位，展开后仍贯穿整卡（包括展开区）。想要整卡含展开区一起变色，才显式传 `'card'`。**展开内容必须放进 `panel`**（`children` 属于头部区），核心才有分区信号。
 
-> EN: `hoverable` (default off) changes the **whole card** on hover and switches the cursor to `pointer`, using `--dshpc-card-hover` (7% blue light / 13% blue dark). `filled` (default on) controls the background — Card uses surface-1, StripCard the accent tint; `false` makes it transparent but keeps the border. Both axes only rewrite `--surface-bg`, so plugins no longer need their own `:hover` rules; a transparent card still changes color on hover.
+> EN: For expandable cards, `hoverScope` selects the scope. The default `'head'` gives the root zero padding and clips the radius, while `__body` — the header block owning all padding — changes color edge to edge; expanding keeps its top and bottom padding symmetric, so the gap between the two blocks changes color too. `__panel` is a sibling with no background and never hovered, so operating inside the expanded area triggers nothing. The StripCard rail is positioned against the root and stays full-height across the expanded area. Pass `'card'` explicitly to include it. **Expandable content must go into `panel`**; `children` belongs to the header block.
 
 | 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
 |---|---|---|---|---|
@@ -377,8 +385,9 @@ h(Surface, { tone: 'sunken', border: 'dashed', padding: 'lg' }, '还没做的东
 | `onToggle` | `() => void` | — | 传了才显示右侧折叠箭头；展开状态由调用方管 | Only shows the right collapse arrow if provided; caller owns the expanded state |
 | `action` | `ReactNode` | — | 右上角操作区 | Top-right action area |
 | `children` | `ReactNode` | — | 主内容，排版随你 | Main content, layout is yours |
-| `panel` | `ReactNode` | — | 展开后才显示的额外内容 | Extra content shown only when expanded |
-| `hoverable` | `boolean` | 'false' | 整卡 hover 变色 + 光标变 pointer，统一 --dshpc-card-hover；默认关 | Whole-card hover plus a pointer cursor, using --dshpc-card-hover; default off |
+| `panel` | `ReactNode` | — | 展开后才显示的额外内容；必须放这里，核心才能把展开区与头部区分开 | Extra content shown only when expanded; must live here so the core can separate it from the header |
+| `hoverable` | `boolean` | 'false' | 悬停变色 + 光标变 pointer，统一 --dshpc-card-hover；默认关 | Hover color plus a pointer cursor, using --dshpc-card-hover; default off |
+| `hoverScope` | `'head' \| 'card'` | 'head' | 'head'（默认）只让上面头部区整块边到边变色、展开区不受影响；'card' 整卡含展开区一起变色。仅 hoverable 为 true 时生效 | 'head' (default) changes only the header block and leaves the expanded area untouched; 'card' includes it. Applies only when hoverable is true |
 | `filled` | `boolean` | 'true' | 是否带底色；false 时底透明、边框仍在。默认有底（Card = surface-1 / StripCard = accent 浅底） | Background fill; false makes it transparent while keeping the border. Default on (Card = surface-1 / StripCard = accent tint) |
 | `className / style` | `—` | — | 追加类 / 样式 | Append class / style |
 
@@ -388,7 +397,7 @@ import { Card, Chip, StripCard } from 'dsh-plugin-core/ui'
 h(Card, {
   accent: 'warning',
   bar: { side: 'left', inset: 12, gap: 12 },   // 色条可放 left / right / top / bottom
-  hoverable: true,                             // 整卡 hover 变色（默认关）
+  hoverable: true,                             // 头部区整块悬停变色（默认关）
   action: h(Button, { size: 'sm', variant: 'ghost' }, '跳过'),
 },
   h('div', null, '标题'),
@@ -398,8 +407,10 @@ h(Card, {
 h(StripCard, {
   accent: 'success',
   hoverable: true, filled: false,              // 底色关掉 = 透明（默认有底）
+  // hoverScope 默认 'head'：只有上面头部区变色，展开区完全不受影响
+  // 要连展开区一起变色才显式写 hoverScope: 'card'
   expanded: open, onToggle: () => setOpen(!open),
-  panel: h('div', null, '展开详情'),
+  panel: h('div', null, '展开详情'),           // 展开内容放 panel，别塞进 children
 }, h('div', null, '标题 + 元信息'))
 ```
 
@@ -407,21 +418,21 @@ h(StripCard, {
 
 > EN: ListRow (one item per line)
 
-一行代表一个可选 / 可点的对象（文件、任务、候选项）：常态就带底色，鼠标移上去按 Button 灰色档加深一档；选中换成 slate 的极浅蓝灰单色背景，不描边、不画竖条。左主内容、右侧一组小操作，点右侧不连带触发整行。底 / 边 / 圆角复用 Surface，颜色全走 token，插件不写第二套皮肤。
+一行代表一个可选 / 可点的对象（文件、任务、候选项）：常态就带底色，鼠标移上去按 Button 灰色档加深一档；选中换成 slate 的极浅蓝灰单色背景，不描边、不画竖条。左主内容、右侧一组小操作，点右侧不连带触发整行。两个槽都自带垂直居中，主内容包成 `inline-flex` 也不会按基线偏上；内部怎么横排仍由调用方定。底 / 边 / 圆角复用 Surface，颜色全走 token，插件不写第二套皮肤。
 
-> EN: One line per selectable / clickable object (file, task, candidate): a visible background at rest that darkens one step on hover using the same grey tokens as Button; selected rows swap to a single pale slate-blue-grey background — no border, no rail. Main content on the left, a group of small actions on the right that never trigger the row. Background / border / radius come from Surface and colors from tokens, so plugins write no second skin.
+> EN: One line per selectable / clickable object (file, task, candidate): a visible background at rest that darkens one step on hover using the same grey tokens as Button; selected rows swap to a single pale slate-blue-grey background — no border, no rail. Main content on the left, a group of small actions on the right that never trigger the row. Both slots are vertically centered by the core, so even an `inline-flex` main-content wrapper does not ride high on the baseline; its internal horizontal layout is still yours. Background / border / radius come from Surface and colors from tokens, so plugins write no second skin.
 
 默认中号（min-height 28，与 Button md 同档），不设 size 轴；四边内距 8px 等距；默认字号 13px / 行高 20px 由核心给（`--dshpc-font-md` / `--dshpc-line-md`，与 Table 同档），调用方不必自己设、可用内联 style 覆盖。`bordered` 切带边 / 不带边，无边档仍是 1px 透明占位，两档同高。`selected` 只改外观，状态由调用方管。
 
 > EN: One medium tier by default (min-height 28, same as Button md); no size axis; equal 8px padding on all four sides. The core sets a default 13px / 20px type scale (`--dshpc-font-md` / `--dshpc-line-md`, same as Table) — callers need not set it and can override it inline. `bordered` switches the edge on/off — the borderless tier keeps a transparent 1px placeholder so heights stay equal. `selected` only changes appearance; the caller owns the state.
 
-`hoverable` 默认跟随「整行可点」（可点行开、纯展示行关，与 Table 的 hover 口径一致），可显式开关；hover / 选中色取 `--dshpc-active` / `--dshpc-listrow-selected-bg`（由 `--dshpc-slate` 派生，亮色 14% / 暗色 26% 两档，暗色不发黑）。整行不是 `<button>`：调用方要往里放 Button / IconButton，嵌 button 是非法 HTML；键盘走 Enter / Space，右侧操作槽挡住冒泡。
+`hoverable` 默认跟随「整行可点」（可点行开、纯展示行关，与 Table 的 hover 口径一致），可显式开关；hover 取 `--dshpc-listrow-hover-bg`，只比常态深一点点（亮 9% 黑 / 暗 10% 白），不会把整行内容和文字对比度一起改掉；选中取 `--dshpc-listrow-selected-bg`（由 `--dshpc-slate` 派生，亮色 14% / 暗色 26% 两档，暗色不发黑）。整行不是 `<button>`：调用方要往里放 Button / IconButton，嵌 button 是非法 HTML；键盘走 Enter / Space，右侧操作槽挡住冒泡。
 
-> EN: `hoverable` follows row clickability by default (on for clickable rows, off for static ones, matching Table), and can be forced on/off; hover / selected use `--dshpc-active` / `--dshpc-listrow-selected-bg` (derived from `--dshpc-slate`, 14% light / 26% dark, so the dark theme never goes black). The row is not a `<button>`: callers put Buttons inside it and nested buttons are invalid HTML. Keyboard uses Enter / Space; the actions slot stops propagation.
+> EN: `hoverable` follows row clickability by default (on for clickable rows, off for static ones, matching Table), and can be forced on/off. Hover uses `--dshpc-listrow-hover-bg`, only a touch deeper than the resting row (9% black light / 10% white dark), so it does not repaint the whole row or shift text contrast; selected uses `--dshpc-listrow-selected-bg` (derived from `--dshpc-slate`, 14% light / 26% dark, so the dark theme never goes black). The row is not a `<button>`: callers put Buttons inside it and nested buttons are invalid HTML. Keyboard uses Enter / Space; the actions slot stops propagation.
 
 | 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
 |---|---|---|---|---|
-| `children` | `ReactNode` | — | 主内容：图标 / 名字 / 标签 / 左右分区自己排 | Main content: icons, labels, tags, left/right layout are yours |
+| `children` | `ReactNode` | — | 主内容：槽自带垂直居中，图标 / 名字 / 标签 / 左右分区自己排 | Main content: the slot centers vertically on its own; icons, labels, tags and left/right layout are yours |
 | `actions` | `ReactNode` | — | 右侧操作槽；核心挡住事件冒泡，不连带整行 | Right-side actions; the core stops propagation so the row is not triggered |
 | `onClick` | `() => void` | — | 给了才让整行可点（role=button / tabIndex / Enter·Space） | Only makes the row clickable when provided (role=button / tabIndex / Enter·Space) |
 | `selected` | `boolean` | 'false' | 选中态：slate 极浅蓝灰单色背景（明暗各一档），不描边 / 不画竖条，压在 hover 之上 | Selected: a single pale slate-blue-grey background (separate light / dark tiers), no border or rail, above hover |

package/package.json

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