Merge remote-tracking branch 'origin/master' into xtr/sidebar-workspace-controls
This commit is contained in:
_Kerman
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md
|
||||
README.md: a9c802c1e43cf06aa0492b39d5052e882a72d9e6
|
||||
README.zh.md: 9e67488ccc1d70263bd0b91d167c4c251ee95926
|
||||
README.md: f96e931472a0946bd023b97b034643f079a67e44
|
||||
README.zh.md: 0db2ac1bccbdc4793c488e1ce621ee5c674d9895
|
||||
|
||||
@@ -2,12 +2,16 @@
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the OnboardingSurface first-run takeover (body-portaled mask + opaque stage that holds `#root` inert for exactly its own lifetime), the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock.
|
||||
Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the Toast transient banner, the OnboardingSurface first-run takeover (body-portaled mask + opaque stage that holds `#root` inert for exactly its own lifetime), the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock.
|
||||
|
||||
## Hover cards
|
||||
|
||||
`HoverCard` keeps its portaled preview reachable across the anchor gap with a pointer-leave grace. A consumer may also pass `copyText`: the card then exposes button semantics for pointer and keyboard activation, includes that value after the `copyLabel` prefix in its accessible name, writes the exact value through the package clipboard helper, and temporarily replaces its content with `copiedLabel` only after the host accepts the write. A non-collapsed text selection intersecting the card suppresses pointer-click activation, while success feedback retains the original card height and clears when the card closes or after one second. `copyLabel` and `copiedLabel` are label props because this zero-cordis atom cannot read the application locale; omitting `copyText` preserves the read/select-only card. Historical rationale: [the archived hover-card copy note](../../../.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md).
|
||||
|
||||
## Toast
|
||||
|
||||
`Toast` is the transient top banner: it slides in, holds at full opacity for three seconds, fades over one second, then calls `onDone` so the owner can unmount it. It renders `role="alert"` with an optional leading icon slot and takes its copy as a required prop (zero-cordis: the owner localizes). It body-portals with `pointer-events: none`, sits 120px from the viewport top, and centers horizontally over the optional `anchor` element (re-measured on window resizes) — the composer passes its card so the banner centers over the chat column rather than the whole window — falling back to the viewport center without one. Re-showing the same message requires a remount — owners key the element by a per-show sequence so an identical repeated message restarts the hold-and-fade cycle instead of silently reusing the faded banner. Under `prefers-reduced-motion: reduce` the slide-in is dropped and only the delayed fade remains. It layers above the ui-attachment image lightbox so a failure reported during a preview stays readable.
|
||||
|
||||
## Markdown rendering
|
||||
|
||||
`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. A narrow micromark extension lets asterisk strong emphasis ending in punctuation close before adjacent CJK text, where prose normally omits the whitespace CommonMark requires; single-asterisk emphasis, non-CJK adjacency, escapes, code, and math retain upstream parsing. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. Inline code whose complete value is an absolute HTTP(S) URL keeps its code styling and gains the same safe external anchor; commands, partial URLs, other schemes, and fenced code remain inert. An optional `fileMentions` resolver lets the owning view link inline code that names a real file: the token keeps code styling and gains a button wired to the resolved opener, with the resolver's accessible label and full-path `title`. The renderer never guesses at what looks like a path — an unresolved token stays inert, mentions apply to settled renders only (the streaming cache must not bake in handlers that could go stale), and a token inside an anchor stays inert because a button cannot nest there. While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail behind them re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply ([mechanism and DOM-parity contract](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)). `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
|
||||
|
||||
@@ -2,12 +2,16 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在且仅在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` 钩子（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。
|
||||
纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、Toast 短时横幅、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在且仅在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` 钩子（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。
|
||||
|
||||
## 悬浮卡片
|
||||
|
||||
`HoverCard` 通过指针离开宽限期，使采用 portal 渲染的预览在跨过与锚点之间的间隙时仍可触及。消费方还可传入 `copyText`：此时卡片为指针与键盘激活提供按钮语义，其无障碍名称会在 `copyLabel` 前缀后包含该值，通过包内剪贴板辅助函数原样写入该值，并且只有宿主接受写入后，才会临时将内容替换为 `copiedLabel`。与卡片相交的非折叠文本选区会阻止指针点击激活；成功反馈保持卡片原有高度，并随卡片关闭或在一秒后清除。`copyLabel` 和 `copiedLabel` 采用 label prop，是因为这个 zero-cordis 原子组件无法读取应用 locale；省略 `copyText` 时，卡片维持只读且可选择文本的行为。历史依据见[已归档的悬浮卡片复制 Agent Note](../../../.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md)。
|
||||
|
||||
## Toast
|
||||
|
||||
`Toast` 是顶部的短时横幅：滑入后满不透明度停留三秒，再用一秒淡出，随后调用 `onDone` 由持有方卸载。它渲染 `role="alert"`，带可选的前置图标插槽，文案是必填 prop（零 cordis，由持有方本地化）。它经 body portal 渲染且 `pointer-events: none`，距视口顶部 120px，水平中心跟随可选的 `anchor` 元素（窗口尺寸变化时重测）——composer 传入自己的卡片，横幅因此在聊天列而非整个窗口上居中——不传则回退到视口居中。重复展示同一条消息需要重新挂载，持有方用每次展示递增的序号作为 key，让相同文案重新走完停留与淡出，而不是静默复用已淡出的横幅。`prefers-reduced-motion: reduce` 下去掉滑入，只保留延迟淡出。它的层级高于 ui-attachment 的图片灯箱，预览打开时报出的失败仍然可读。
|
||||
|
||||
## Markdown 渲染
|
||||
|
||||
`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有该组件的视图为命名真实文件的行内代码添加可点击入口：token 保留代码样式，并获得一个连接到解析所得 opener 的按钮，按钮带有解析器提供的无障碍标签和以完整路径为值的 `title`。渲染器绝不猜测哪些内容像路径：未解析的 token 保持不可交互；文件提及仅应用于已定稿的渲染（流式缓存不得固化可能过期的 handler）；锚点内的 token 也保持不可交互，因为按钮不能嵌套其中。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性约定](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
|
||||
|
||||
70
packages/client/ui-primitives/src/Toast.module.css
Normal file
70
packages/client/ui-primitives/src/Toast.module.css
Normal file
@@ -0,0 +1,70 @@
|
||||
/* Transient top-center banner (DeepSeek Chat toast look): contrast fill,
|
||||
inverted label, slide-in, then hold-and-fade. The fade delay/duration MUST
|
||||
agree with HOLD_MS/FADE_MS in Toast.tsx: the component unmounts at their
|
||||
sum, so a mismatched sheet either cuts the fade or leaves an invisible
|
||||
banner blocking nothing. */
|
||||
|
||||
.toast {
|
||||
position: fixed;
|
||||
top: 120px;
|
||||
left: 50%;
|
||||
/* Above the 1000 the image lightbox backdrop uses: a failure reported while
|
||||
a preview is open must stay readable. */
|
||||
z-index: 1100;
|
||||
/* Purely an announcement: it must never intercept clicks — in particular
|
||||
after the CSS fade finished while a throttled background-tab timer has
|
||||
not yet unmounted the still-hit-testable fixed element. */
|
||||
pointer-events: none;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 10px;
|
||||
max-width: min(560px, calc(100vw - 48px));
|
||||
padding: 12px 16px;
|
||||
border-radius: 14px;
|
||||
background: var(--dsw-alias-button-contrast-fill);
|
||||
color: var(--dsw-alias-label-primary-inverted);
|
||||
font-size: 14px;
|
||||
line-height: 22px;
|
||||
box-shadow: var(--dsw-shadow-lv3);
|
||||
transform: translateX(-50%);
|
||||
animation:
|
||||
dsh-toast-in 160ms ease-out,
|
||||
dsh-toast-fade 1000ms ease 3000ms forwards;
|
||||
}
|
||||
|
||||
.icon {
|
||||
display: grid;
|
||||
place-items: center;
|
||||
flex: none;
|
||||
color: var(--dsw-alias-state-warn-label);
|
||||
}
|
||||
|
||||
.text {
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
@keyframes dsh-toast-in {
|
||||
from {
|
||||
opacity: 0;
|
||||
transform: translate(-50%, -6px);
|
||||
}
|
||||
|
||||
to {
|
||||
opacity: 1;
|
||||
transform: translate(-50%, 0);
|
||||
}
|
||||
}
|
||||
|
||||
@keyframes dsh-toast-fade {
|
||||
to {
|
||||
opacity: 0;
|
||||
}
|
||||
}
|
||||
|
||||
/* Reduced motion drops the slide-in; the delayed fade (an opacity change,
|
||||
not movement) still ends the banner before the timed unmount. */
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
.toast {
|
||||
animation: dsh-toast-fade 1000ms ease 3000ms forwards;
|
||||
}
|
||||
}
|
||||
59
packages/client/ui-primitives/src/Toast.tsx
Normal file
59
packages/client/ui-primitives/src/Toast.tsx
Normal file
@@ -0,0 +1,59 @@
|
||||
import { useEffect, useLayoutEffect, useState } from 'react'
|
||||
import type { ReactNode } from 'react'
|
||||
import { createPortal } from 'react-dom'
|
||||
import css from './Toast.module.css'
|
||||
|
||||
/** Full-opacity hold before the fade starts. Must agree with the stylesheet's
|
||||
* toast-fade delay (Toast.module.css) or the banner unmounts mid-fade. */
|
||||
const HOLD_MS = 3000
|
||||
/** Fade duration. Must agree with the stylesheet's toast-fade duration. */
|
||||
const FADE_MS = 1000
|
||||
|
||||
/**
|
||||
* Transient top-center banner: slides in, holds at full opacity, fades out,
|
||||
* then reports done so the owner can unmount it. Re-showing the same text
|
||||
* restarts the cycle when the owner remounts the component (key it by a
|
||||
* per-show sequence). Rendered through a body portal so an owner inside a
|
||||
* transformed or filtered ancestor cannot trap the fixed banner in that
|
||||
* ancestor's box.
|
||||
*
|
||||
* @param props.text - resolved banner copy; the owner passes localized text.
|
||||
* @param props.icon - optional leading glyph (e.g. a warning icon).
|
||||
* @param props.anchor - optional element whose horizontal center the banner
|
||||
* follows (e.g. the composer card, so the banner centers over the chat column
|
||||
* rather than the whole window); omitted, it centers on the viewport.
|
||||
* @param props.onDone - called once the fade completes; unmount the toast here.
|
||||
* @returns the floating banner.
|
||||
*/
|
||||
export function Toast({ text, icon, anchor, onDone }: {
|
||||
text: string
|
||||
icon?: ReactNode
|
||||
anchor?: HTMLElement | null
|
||||
onDone: () => void
|
||||
}) {
|
||||
useEffect(() => {
|
||||
const timer = setTimeout(onDone, HOLD_MS + FADE_MS)
|
||||
return () => { clearTimeout(timer) }
|
||||
}, [onDone])
|
||||
// Anchor-centered placement re-measures on window resizes; the banner lives
|
||||
// four seconds, so sub-window layout drift within that span stays out of
|
||||
// scope.
|
||||
const [left, setLeft] = useState<number | null>(null)
|
||||
useLayoutEffect(() => {
|
||||
if (anchor == null) return
|
||||
const measure = (): void => {
|
||||
const rect = anchor.getBoundingClientRect()
|
||||
setLeft(rect.left + rect.width / 2)
|
||||
}
|
||||
measure()
|
||||
window.addEventListener('resize', measure)
|
||||
return () => { window.removeEventListener('resize', measure) }
|
||||
}, [anchor])
|
||||
return createPortal(
|
||||
<div className={css.toast} role="alert" style={left === null ? undefined : { left }}>
|
||||
{icon !== undefined && <span className={css.icon} aria-hidden>{icon}</span>}
|
||||
<span className={css.text}>{text}</span>
|
||||
</div>,
|
||||
document.body,
|
||||
)
|
||||
}
|
||||
@@ -23,6 +23,7 @@ export { FishLogo } from './FishLogo.tsx'
|
||||
export { BrandWordmark } from './BrandWordmark.tsx'
|
||||
export { Tooltip } from './Tooltip.tsx'
|
||||
export type { TooltipSide } from './Tooltip.tsx'
|
||||
export { Toast } from './Toast.tsx'
|
||||
export { writeClipboard } from './clipboard.ts'
|
||||
export { JsonTree } from './JsonTree.tsx'
|
||||
export type { JsonTreeProps, JsonTreeLabels } from './JsonTree.tsx'
|
||||
|
||||
57
packages/client/ui-primitives/tests/toast.spec.tsx
Normal file
57
packages/client/ui-primitives/tests/toast.spec.tsx
Normal file
@@ -0,0 +1,57 @@
|
||||
// @vitest-environment jsdom
|
||||
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest'
|
||||
import { cleanup, fireEvent, render } from '@testing-library/react'
|
||||
import { Toast } from '../src/Toast.tsx'
|
||||
|
||||
afterEach(cleanup)
|
||||
|
||||
describe('Toast', () => {
|
||||
it('announces its text and reports done after the hold-and-fade lifetime', () => {
|
||||
vi.useFakeTimers()
|
||||
try {
|
||||
const onDone = vi.fn()
|
||||
const view = render(<Toast text="最多添加 50 张图片" icon={<svg data-testid="icon" />} onDone={onDone} />)
|
||||
const banner = view.getByRole('alert')
|
||||
expect(banner.textContent).toContain('最多添加 50 张图片')
|
||||
expect(view.getByTestId('icon')).toBeTruthy()
|
||||
vi.advanceTimersByTime(3999)
|
||||
expect(onDone).not.toHaveBeenCalled()
|
||||
vi.advanceTimersByTime(1)
|
||||
expect(onDone).toHaveBeenCalledTimes(1)
|
||||
} finally {
|
||||
vi.useRealTimers()
|
||||
}
|
||||
})
|
||||
|
||||
it('centers over its anchor and re-measures on window resize', () => {
|
||||
vi.useFakeTimers()
|
||||
try {
|
||||
const anchor = document.createElement('div')
|
||||
document.body.appendChild(anchor)
|
||||
anchor.getBoundingClientRect = () => ({ left: 100, width: 400 }) as DOMRect
|
||||
const view = render(<Toast text="anchored" anchor={anchor} onDone={vi.fn()} />)
|
||||
expect(view.getByRole('alert').style.left).toBe('300px')
|
||||
anchor.getBoundingClientRect = () => ({ left: 200, width: 400 }) as DOMRect
|
||||
fireEvent(window, new Event('resize'))
|
||||
expect(view.getByRole('alert').style.left).toBe('400px')
|
||||
anchor.remove()
|
||||
} finally {
|
||||
vi.useRealTimers()
|
||||
}
|
||||
})
|
||||
|
||||
it('renders without an icon and cancels its timer on unmount', () => {
|
||||
vi.useFakeTimers()
|
||||
try {
|
||||
const onDone = vi.fn()
|
||||
const view = render(<Toast text="plain" onDone={onDone} />)
|
||||
expect(view.getByRole('alert').querySelector('[aria-hidden]')).toBeNull()
|
||||
view.unmount()
|
||||
vi.advanceTimersByTime(10_000)
|
||||
expect(onDone).not.toHaveBeenCalled()
|
||||
} finally {
|
||||
vi.useRealTimers()
|
||||
}
|
||||
})
|
||||
})
|
||||
Reference in New Issue
Block a user