@logictan/dsh-config-manager 0.1.60

package/src/client/common/toast-store.ts

@@ -0,0 +1,181 @@
+/**
+ * Toast Store —— 全局通知的纯逻辑状态机（零 DOM、零 React，node 可单测）。
+ *
+ * 为什么独立成 store：插件里大量「操作完成后临时提示」原先散落在各页的局部 state
+ * （`flash` / `feedback` / `saved`）里，只能渲染在页面内容流中、切页即丢失、还会把
+ * 页面顶开一块。统一到模块级 store 后可跨页面存活，并集中处理去重、同屏上限与自动消失。
+ *
+ * 设计要点：
+ *   - 订阅式（`subscribe`/`getSnapshot`）对接 `useSyncExternalStore`；snapshot 引用仅在
+ *     真正变更时替换，避免 React 无限重渲染。
+ *   - 计时器依赖注入（`schedule`/`cancel`）：测试里可用假计时器精确驱动，不必等真实时间。
+ *   - 同 `kind + text` 已在屏时**不重复入队**，只重置计时（防连点导致刷屏）。
+ *   - 同屏上限 `maxVisible`（默认 4）：超出时挤掉最旧的一条，连其计时器一并清理。
+ *   - 空文案（trim 后为空）直接忽略，杜绝空白通知条。
+ */
+import type { ToastKind } from './toast-types.ts'
+
+export type { ToastKind }
+
+/** 单条通知。 */
+export interface ToastItem {
+  id: number
+  kind: ToastKind
+  text: string
+  /** 自动消失毫秒数；0 = 不自动消失（须手动关闭） */
+  durationMs: number
+}
+
+/** store 快照（`getSnapshot` 返回的稳定引用）。 */
+export interface ToastSnapshot {
+  items: ToastItem[]
+}
+
+/** 计时器句柄（浏览器为 number，node 为 Timeout，测试可自定义）。 */
+export type ToastTimerHandle = unknown
+
+export interface ToastStoreOptions {
+  /** 同屏最大条数（默认 4）；超出挤掉最旧。 */
+  maxVisible?: number
+  /** 排定计时器（默认 setTimeout），测试可注入假实现。 */
+  schedule?: (fn: () => void, ms: number) => ToastTimerHandle
+  /** 取消计时器（默认 clearTimeout）。 */
+  cancel?: (handle: ToastTimerHandle) => void
+}
+
+/** 各语义的默认停留时长：成功/普通短、失败/警告长（错误需要更多阅读时间）。 */
+export const DEFAULT_DURATION_MS: Record<ToastKind, number> = {
+  ok: 3200,
+  info: 3200,
+  warn: 5200,
+  error: 6400,
+}
+
+/** 同屏上限：超过 4 条会盖住插件画布右下角的大片区域。 */
+export const MAX_VISIBLE = 4
+
+const EMPTY: ToastSnapshot = { items: [] }
+
+/**
+ * 全局通知状态机。通常只用下方的 `toast` 单例，测试时可直接 new 一个隔离实例。
+ */
+export class ToastStore {
+  private items: ToastItem[] = []
+  private readonly timers = new Map<number, ToastTimerHandle>()
+  private readonly listeners = new Set<() => void>()
+  private nextId = 1
+  private snapshot: ToastSnapshot = EMPTY
+  private readonly maxVisible: number
+  private readonly schedule: (fn: () => void, ms: number) => ToastTimerHandle
+  private readonly cancel: (handle: ToastTimerHandle) => void
+
+  constructor(options: ToastStoreOptions = {}) {
+    this.maxVisible = options.maxVisible ?? MAX_VISIBLE
+    this.schedule = options.schedule ?? ((fn, ms) => setTimeout(fn, ms))
+    this.cancel = options.cancel ?? ((handle) => { clearTimeout(handle as ReturnType<typeof setTimeout>) })
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  getSnapshot = (): ToastSnapshot => this.snapshot
+
+  /**
+   * 推入一条通知。返回该条 id；空文案返回 0（表示未入队）。
+   * 同 kind+text 已在屏时复用原条目并重置计时。
+   */
+  push(kind: ToastKind, text: string, durationMs?: number): number {
+    const value = text.trim()
+    if (value === '') return 0
+    const duration = durationMs ?? DEFAULT_DURATION_MS[kind]
+
+    const existing = this.items.find((t) => t.kind === kind && t.text === value)
+    if (existing !== undefined) {
+      this.arm(existing.id, duration)
+      return existing.id
+    }
+
+    const id = this.nextId++
+    const next: ToastItem[] = [...this.items, { id, kind, text: value, durationMs: duration }]
+    const overflowCount = Math.max(0, next.length - this.maxVisible)
+    for (const stale of next.slice(0, overflowCount)) this.disarm(stale.id)
+    this.items = next.slice(overflowCount)
+    this.arm(id, duration)
+    this.commit()
+    return id
+  }
+
+  /** 关闭指定通知（手动关闭 / 计时到期共用）。 */
+  dismiss(id: number): void {
+    if (!this.items.some((t) => t.id === id)) return
+    this.disarm(id)
+    this.items = this.items.filter((t) => t.id !== id)
+    this.commit()
+  }
+
+  /**
+   * 重新计时（悬停暂停用）：取消该条当前计时并按 `durationMs`（缺省沿用原时长）重新排定。
+   * 不改变条目位置与内容，因此不产生新快照——避免悬停时触发无谓重渲染。
+   */
+  resetTimer(id: number, durationMs?: number): void {
+    const item = this.items.find((t) => t.id === id)
+    if (item === undefined) return
+    this.arm(id, durationMs ?? item.durationMs)
+  }
+
+  /** 暂停自动消失（悬停）：仅取消计时，条目与位置不变。 */
+  pauseTimer(id: number): void {
+    if (!this.items.some((t) => t.id === id)) return
+    this.disarm(id)
+  }
+
+  /** 清空全部通知。 */
+  clear(): void {
+    if (this.items.length === 0) return
+    for (const item of this.items) this.disarm(item.id)
+    this.items = []
+    this.commit()
+  }
+
+  /** 排定 / 重置某条的自动消失计时；durationMs <= 0 表示常驻。 */
+  private arm(id: number, durationMs: number): void {
+    this.disarm(id)
+    if (durationMs <= 0) return
+    this.timers.set(id, this.schedule(() => { this.dismiss(id) }, durationMs))
+  }
+
+  private disarm(id: number): void {
+    const handle = this.timers.get(id)
+    if (handle === undefined) return
+    this.cancel(handle)
+    this.timers.delete(id)
+  }
+
+  /** 提交新快照并通知订阅者（仅在真正变化时调用）。 */
+  private commit(): void {
+    this.snapshot = { items: this.items }
+    for (const listener of this.listeners) listener()
+  }
+}
+
+/** 进程级单例（插件内所有页面共用一套通知队列）。 */
+export const toastStore = new ToastStore()
+
+/**
+ * 面向业务代码的调用入口。
+ *
+ *   toast.ok('已保存配置档案')
+ *   toast.error(redact(err.message))
+ *
+ * 约定：文案在调用前完成 i18n 与 `redact()`（本模块不碰翻译与脱敏）。
+ */
+export const toast = {
+  ok: (text: string, durationMs?: number): number => toastStore.push('ok', text, durationMs),
+  info: (text: string, durationMs?: number): number => toastStore.push('info', text, durationMs),
+  warn: (text: string, durationMs?: number): number => toastStore.push('warn', text, durationMs),
+  error: (text: string, durationMs?: number): number => toastStore.push('error', text, durationMs),
+  dismiss: (id: number): void => { toastStore.dismiss(id) },
+  clear: (): void => { toastStore.clear() },
+}

package/src/client/common/toast-types.ts

@@ -0,0 +1,7 @@
+/**
+ * Toast 公共类型 —— 独立成文件是为了让 store（无 React）与视图（React）都能引用，
+ * 且不产生「store → 视图」的反向依赖。
+ */
+
+/** 通知语义：与 Badge / Banner / StatusDot 的既有四态保持一致。 */
+export type ToastKind = 'ok' | 'info' | 'warn' | 'error'

package/src/client/common/ui.tsx

@@ -0,0 +1,342 @@
+/**
+ * Config Manager 基础 UI 原语 —— Workbench Design System（2026-09 Full UI Rebuild）。
+ * 全部走 DSH Design System 的 --dsw-* token，不另造视觉体系；类名来自
+ * config-manager.module.css，无业务逻辑。
+ *
+ * 本文件是重建后的原语层：在既有 API（Button/Badge/Banner/Card/Spinner/Field/
+ * SectionTitle/Empty/Checkbox/Stepper）完全兼容的前提下，新增：
+ *   - Button size（'sm' 密集场景）
+ *   - IconButton（导航/工具栏图标动作）
+ *   - StatusDot（状态栏/行内状态点）
+ *   - Segmented（页内子视图分段切换）
+ */
+import type { ChangeEvent, CSSProperties, ReactNode } from 'react'
+import css from '../config-manager.module.css'
+
+/* ---------------- Button ---------------- */
+
+export type ButtonVariant = 'primary' | 'ghost' | 'danger'
+export type ButtonSize = 'sm' | 'md'
+
+export interface ButtonProps {
+  variant?: ButtonVariant
+  /** 尺寸：sm = 表格行内/密集工具栏（24px）；md = 常规（28px，缺省） */
+  size?: ButtonSize
+  disabled?: boolean
+  /** 进行中态：自动 disabled + aria-busy（children 由调用方渲染 Spinner 保持现状） */
+  loading?: boolean
+  onClick?: () => void
+  children: ReactNode
+  title?: string
+  className?: string
+  /** 外链 URL：存在时渲染 <a>（新窗口 + noreferrer，防 tabnabbing），否则渲染 <button> */
+  href?: string
+  /** 是否新窗口打开（仅 href 存在时生效；默认 true） */
+  newTab?: boolean
+}
+
+/**
+ * 统一按钮（primary=主操作 / ghost=次操作 / danger=危险操作）。
+ * 带 href 时渲染同款按钮类的外链 <a>；loading=true 时自动禁用并标注 aria-busy。
+ */
+export function Button({ variant = 'ghost', size, disabled, loading = false, onClick, children, title, className, href, newTab = true }: ButtonProps) {
+  const cls =
+    variant === 'primary' ? css.primaryButton
+      : variant === 'danger' ? css.dangerButton
+        : css.ghostButton
+  const effectiveDisabled = disabled === true || loading
+  const sizeProps = size === 'sm' ? { 'data-size': 'sm' as const } : {}
+  if (href !== undefined) {
+    return (
+      <a
+        className={className !== undefined ? `${cls} ${className}` : cls}
+        href={href}
+        target={newTab ? '_blank' : undefined}
+        rel={newTab ? 'noreferrer' : undefined}
+        title={title}
+        aria-busy={loading || undefined}
+        onClick={onClick}
+        // 按钮类无 text-decoration 规则，<a> 默认下划线破坏按钮外观
+        style={{ textDecoration: 'none' }}
+        {...sizeProps}
+      >
+        {children}
+      </a>
+    )
+  }
+  return (
+    <button
+      type="button"
+      className={className !== undefined ? `${cls} ${className}` : cls}
+      disabled={effectiveDisabled}
+      title={title}
+      aria-busy={loading || undefined}
+      onClick={onClick}
+      {...sizeProps}
+    >
+      {children}
+    </button>
+  )
+}
+
+/* ---------------- IconButton ---------------- */
+
+export interface IconButtonProps {
+  /** 图标/符号（文本符号；aria-label 必填描述用途） */
+  icon: ReactNode
+  /** 无障碍名称（必填：图标按钮没有可见文本） */
+  label: string
+  onClick?: () => void
+  disabled?: boolean
+  /** 高亮态（如抽屉打开时对应按钮 active） */
+  active?: boolean
+  /** 危险语义（红色；用于行内删除等破坏性动作的视觉隔离） */
+  danger?: boolean
+  title?: string
+}
+
+/** 图标按钮（导航条/工具栏图标动作；26px 触达区）。 */
+export function IconButton({ icon, label, onClick, disabled, active, danger, title }: IconButtonProps) {
+  return (
+    <button
+      type="button"
+      className={css.iconBtn}
+      aria-label={label}
+      title={title ?? label}
+      data-active={active === true ? '' : undefined}
+      data-danger={danger === true ? '' : undefined}
+      disabled={disabled === true}
+      onClick={onClick}
+    >
+      {icon}
+    </button>
+  )
+}
+
+/* ---------------- StatusDot ---------------- */
+
+export type StatusDotKind = 'idle' | 'ok' | 'info' | 'warn' | 'error'
+
+export interface StatusDotProps {
+  kind?: StatusDotKind
+  /** 进行中脉冲动画 */
+  pulse?: boolean
+}
+
+/** 状态点（状态栏/行内状态指示）。 */
+export function StatusDot({ kind = 'idle', pulse }: StatusDotProps) {
+  return (
+    <span
+      className={css.statusDot}
+      data-kind={kind === 'idle' ? undefined : kind}
+      data-pulse={pulse === true ? '' : undefined}
+      aria-hidden="true"
+    />
+  )
+}
+
+/* ---------------- Badge ---------------- */
+
+export type BadgeKind = 'info' | 'ok' | 'warn' | 'error'
+
+export interface BadgeProps {
+  kind?: BadgeKind
+  children: ReactNode
+  /** 悬停提示（可选） */
+  title?: string
+}
+
+/** 状态徽章（info=业务色 / ok=成功 / warn=警告 / error=错误）。 */
+export function Badge({ kind = 'info', children, title }: BadgeProps) {
+  return <span className={`${css.badge} ${css[`badge${kind[0]!.toUpperCase()}${kind.slice(1)}`] ?? ''}`} title={title}>{children}</span>
+}
+
+/* ---------------- Banner ---------------- */
+
+export type BannerKind = 'ok' | 'error' | 'info' | 'warn'
+
+export interface BannerProps {
+  kind?: BannerKind
+  children: ReactNode
+}
+
+/** 说明横幅（ok/error/info/warn 四态） */
+export function Banner({ kind = 'info', children }: BannerProps) {
+  return <div className={css.banner} data-kind={kind}>{children}</div>
+}
+
+/* ---------------- Card ---------------- */
+
+export interface CardProps {
+  children: ReactNode
+  className?: string
+  /** 少量布局微调（flex 填充等）；常规布局仍走 CSS 类 */
+  style?: CSSProperties
+}
+
+/** 卡片容器（bg-layer-2 + 细边框） */
+export function Card({ children, className, style }: CardProps) {
+  return <div className={className !== undefined ? `${css.card} ${className}` : css.card} style={style}>{children}</div>
+}
+
+/* ---------------- Spinner ---------------- */
+
+export interface SpinnerProps {
+  label?: string
+}
+
+/** 加载指示（旋转环 + 可选文案） */
+export function Spinner({ label }: SpinnerProps) {
+  return (
+    <span className={css.spinnerWrap}>
+      <span className={css.spinner} aria-hidden="true" />
+      {label !== undefined && <span className={css.spinnerLabel}>{label}</span>}
+    </span>
+  )
+}
+
+/* ---------------- Field ---------------- */
+
+export interface FieldProps {
+  label: string
+  hint?: string
+  children: ReactNode
+}
+
+/** 表单字段（标签 + 控件 + 说明） */
+export function Field({ label, hint, children }: FieldProps) {
+  return (
+    <label className={css.field}>
+      <span className={css.fieldLabel}>{label}</span>
+      {children}
+      {hint !== undefined && <span className={css.hint}>{hint}</span>}
+    </label>
+  )
+}
+
+/* ---------------- SectionTitle ---------------- */
+
+export interface SectionTitleProps {
+  title: string
+  subtitle?: string
+}
+
+/** 区块标题（页面内二级标题 + 可选副标题） */
+export function SectionTitle({ title, subtitle }: SectionTitleProps) {
+  return (
+    <div className={css.sectionTitleBlock}>
+      <h3 className={css.sectionTitle}>{title}</h3>
+      {subtitle !== undefined && <p className={css.sectionSubtitle}>{subtitle}</p>}
+    </div>
+  )
+}
+
+/* ---------------- Empty / Loading ---------------- */
+
+export interface EmptyProps {
+  children: ReactNode
+}
+
+/** 空状态占位 */
+export function Empty({ children }: EmptyProps) {
+  return <div className={css.empty}>{children}</div>
+}
+
+/* ---------------- Checkbox ---------------- */
+
+export interface CheckboxProps {
+  checked: boolean
+  onChange: (checked: boolean) => void
+  label: ReactNode
+  disabled?: boolean
+}
+
+/** 复选框行（勾选 + 标签） */
+export function Checkbox({ checked, onChange, label, disabled }: CheckboxProps) {
+  return (
+    <label className={css.checkboxRow}>
+      <input
+        type="checkbox"
+        checked={checked}
+        disabled={disabled}
+        onChange={(event: ChangeEvent<HTMLInputElement>) => { onChange(event.target.checked) }}
+      />
+      <span>{label}</span>
+    </label>
+  )
+}
+
+/* ---------------- Segmented ---------------- */
+
+export interface SegmentedItem {
+  id: string
+  label: string
+  /** 计数徽标（可选；如市场分区筛选计数） */
+  count?: number
+}
+
+export interface SegmentedProps {
+  items: SegmentedItem[]
+  active: string
+  onChange: (id: string) => void
+  ariaLabel?: string
+}
+
+/** 分段控件（页内子视图切换；受控）。 */
+export function Segmented({ items, active, onChange, ariaLabel }: SegmentedProps) {
+  return (
+    <div className={css.segGroup} role="tablist" aria-label={ariaLabel}>
+      {items.map((item) => (
+        <button
+          key={item.id}
+          type="button"
+          role="tab"
+          aria-selected={item.id === active}
+          data-active={item.id === active ? '' : undefined}
+          className={css.segItem}
+          onClick={() => { onChange(item.id) }}
+        >
+          {item.label}
+          {item.count !== undefined && <span aria-hidden="true">·{item.count}</span>}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+/* ---------------- Stepper ---------------- */
+
+export type StepperStepState = 'done' | 'current' | 'todo'
+
+export interface StepperStep {
+  /** 步骤唯一 key（React list key）。 */
+  key: string
+  label: string
+  state: StepperStepState
+}
+
+export interface StepperProps {
+  steps: StepperStep[]
+  /** 可访问性说明（如「第 2 步，共 6 步」）；存在时容器带 role=group + aria-label */
+  ariaLabel?: string
+}
+
+/**
+ * 向导步骤条（只读指示器，非导航）：紧凑圆点（序号/✓）+ 连接线 + 标签。
+ * state 由调用方的纯函数模型给出；组件不做任何状态推断。
+ */
+export function Stepper({ steps, ariaLabel }: StepperProps) {
+  return (
+    <div className={css.stepper} role={ariaLabel !== undefined ? 'group' : 'list'} aria-label={ariaLabel}>
+      {steps.map((step, i) => (
+        <span key={step.key} role="listitem" className={css.stepperStep} data-state={step.state}>
+          <span className={css.stepperDot} data-state={step.state} aria-hidden="true">
+            {step.state === 'done' ? '✓' : i + 1}
+          </span>
+          <span className={css.stepperLabel}>{step.label}</span>
+          {i < steps.length - 1 && <span className={css.stepperConnector} aria-hidden="true" />}
+        </span>
+      ))}
+    </div>
+  )
+}