@xiongtao.xt/tau-plugins 0.0.0-stage → 0.2.0

package/types/packages/themes/src/themes/ocean.theme.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 主题「海盐」—— 取自移动端海盐 Ocean（浅色·沉静）：盐雾蓝灰纸底 + 石板墨 + 海盐蓝 accent。
+ *
+ * 浅色（晴）：底色 / 墨色 / 品牌蓝沿用移动端取值；桌面对比度门禁更严（02 规范 §2.5），
+ * ink-2 与 accent 按 AA 压深，并补齐移动端没有的 sunken / track 档。
+ *
+ * 深色（夜）：移动端无深色版，按同色相推演为「夜海」——深海军蓝底 + 盐白墨 + 海盐蓝提亮。
+ * 层级与浅色对称翻转（同暖纸 · 夜的口径）：surface 最亮、sunken 最暗；交互态改盐白墨低透明
+ * 叠层；阴影加深至黑系。
+ */
+declare const _default: import("../defineTheme").ThemeDefinition;
+export default _default;

package/types/packages/themes/src/themes/paper.theme.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 主题「暖纸」—— 首个主题族，一张暖纸的晨与夜。
+ *
+ * 浅色（晨）：取值来自样板间 direction-a-soft.html 的实测调优结果；奶油纸底 + 可可墨 +
+ * 陶土橙 accent（与移动端「杏子 Bento」同基因）。融合骨架要求：不提供侧栏专用底色，
+ * 侧栏透明融于 bg-page（见 03 指南 · 壳层铁律）。
+ *
+ * 深色（夜）：同一张暖纸在烛光下——深可可纸底 + 奶油墨 + 陶土橙提亮。层级与浅色对称翻转：
+ * surface 最亮（卡片浮起）、sunken 最暗（凹陷）；交互态改奶油墨低透明叠层（对应浅色的
+ * 可可墨叠层）；阴影加深至黑系。
+ *
+ * 对比度按 02 规范 §2.5：ink-1 对 page/surface ≥ 7:1、ink-2 与 accent 文字 ≥ 4.5:1
+ * （由 theme-parity.test.ts 的对比度断言守护，深浅两套都校验）。
+ */
+declare const _default: import("../defineTheme").ThemeDefinition;
+export default _default;

package/types/packages/themes/src/themes/sakura.theme.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 主题「樱花」—— 樱粉纸底 + 梅褐墨 + 莓粉 accent，温柔明亮。
+ *
+ * 浅色（晴）：纸底粉调强度对齐暖纸的暖调；accent 受 AA 所限明度不能高，粉感靠高饱和
+ * （62%）撑起，选中 / soft 底透明度也提一档让粉色在界面里可见；danger 偏橙红，与莓粉拉开。
+ * 深色（夜樱）：夜底带一层梅粉调（可辨但不整页泛粉）+ 樱白墨 + 高饱和莓粉 accent。
+ *
+ * 对比度按 02 规范 §2.5，深浅两套均由 theme-parity.test.ts 校验。
+ */
+declare const _default: import("../defineTheme").ThemeDefinition;
+export default _default;

package/types/packages/themes/src/themes/wisteria.theme.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 主题「紫藤」—— 淡紫灰纸底 + 暮紫墨 + 紫藤色 accent，柔和文艺。
+ *
+ * 浅色（晴）：纸底带一丝紫调，墨色取暮紫而非纯黑，accent 为中明度紫藤色。
+ * 深色（夜紫）：深紫夜底 + 藤白墨 + 紫藤提亮；层级口径同暖纸 · 夜。
+ *
+ * 对比度按 02 规范 §2.5，深浅两套均由 theme-parity.test.ts 校验。
+ */
+declare const _default: import("../defineTheme").ThemeDefinition;
+export default _default;

package/types/packages/themes/src/tokenContract.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 语义 token 词汇表 —— 单一事实源。
+ *
+ * 词汇表同时产出三样东西：
+ *  1. TS 类型 SemanticTokens（主题作者必须补齐全部键，漏键编译不过）；
+ *  2. CSS 变量名（--tau-<word>，themeStore 注入到 html）；
+ *  3. tokens.css 中 @theme inline 的映射依据（颜色类名 = 词汇名）。
+ *
+ * 规则（见 docs/redesign/02-UI设计系统规范.md §2）：
+ *  - 组件只允许消费 --tau-*（或经 Tailwind 映射的语义类名 bg-page / text-ink-1…）；
+ *  - palette 原始输入不进组件；尺度（字号/间距/圆角/动效）与主题正交，在 tokens.css :root 定义。
+ */
+export declare const tokenContract: {
+    readonly surface: readonly ["bg-page", "bg-surface", "bg-surface-hover", "bg-sunken"];
+    readonly control: readonly ["bg-track"];
+    readonly interaction: readonly ["bg-hover", "bg-press", "bg-selected"];
+    readonly ink: readonly ["ink-1", "ink-2", "ink-3", "ink-inverse"];
+    readonly line: readonly ["line-1", "line-2"];
+    readonly accent: readonly ["accent", "accent-hover", "accent-soft", "accent-text", "focus-ring"];
+    readonly status: readonly ["ok", "ok-soft", "warn", "warn-soft", "danger", "danger-soft", "info", "info-soft"];
+    readonly tag: readonly ["tag-1", "tag-1-soft", "tag-2", "tag-2-soft", "tag-3", "tag-3-soft", "tag-4", "tag-4-soft", "tag-5", "tag-5-soft"];
+    readonly float: readonly ["overlay", "shadow-card", "shadow-lift", "shadow-float", "shadow-paper"];
+};
+/** 全部词汇的平铺联合类型 */
+export type TokenWord = (typeof tokenContract)[keyof typeof tokenContract][number];
+/** 主题必须提供的 token 取值表（全键 Required——漏一个编译不过） */
+export type SemanticTokens = Record<TokenWord, string>;
+/** CSS 变量名约定：--tau-<word>（如 --tau-bg-page）。 */
+export declare function cssVarName(word: string): string;
+export declare const ALL_TOKEN_WORDS: readonly TokenWord[];

package/types/packages/ui/src/UiProvider.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from "react";
+import { type ThemeMode } from "../../themes/src/index";
+export declare function usePortalContainer(): HTMLElement;
+/** 模态内的浮层留在同一层叠上下文，挂载点避开正文滚动区。 */
+export declare function PortalScope({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 局部主题作用域：theme / mode 任一给定即建立作用域（数据块按 主题族 × 明暗 双属性匹配，
+ * 缺省的一侧取默认主题族 / 浅色）；都不给则继承 <html> 上的全局主题。
+ */
+export declare function UiProvider({ children, theme, mode, className, }: {
+    children: ReactNode;
+    theme?: string;
+    mode?: ThemeMode;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/cn.d.ts

@@ -0,0 +1,23 @@
+/**
+ * className 合并 —— clsx 做条件拼接，tailwind-merge 去掉同属性冲突项。
+ *
+ * 组件基础类与调用方 className 撞同一属性时（size-[30px] vs size-[27px]、
+ * items-start vs items-center），Tailwind 生成顺序决定胜负、clsx 的先后顺序无效，
+ * 覆盖会被静默吞掉——凡允许 className 覆盖默认样式处（primitives、样板间 kit）都用本函数。
+ *
+ * 自定义尺度词（text-tau-*、rounded-tau-*、shadow-card…）tailwind-merge 默认不认识，
+ * 会把 text-tau-meta 当颜色组而与 text-ink-2 互相残杀（后写赢、字号类被删）。下表把它们
+ * 登记进正确的 classGroup；与 tokens.css 的一致性由 __tests__/cn.test.ts 守护，
+ * 新增尺度词必须同步登记。
+ */
+import { type ClassValue } from "clsx";
+/** 尺度词表（值不含类名前缀：text-tau-meta 记为 tau-meta） */
+export declare const SCALE_WORDS: {
+    readonly fontSize: readonly ["tau-hero", "tau-title-lg", "tau-title", "tau-body-lg", "tau-body", "tau-meta", "tau-sm", "tau-micro", "tau-tiny"];
+    readonly fontFamily: readonly ["tau", "tau-mono", "tau-hand"];
+    readonly radius: readonly ["tau-sm", "tau-md", "tau-lg"];
+    readonly shadow: readonly ["card", "lift", "float", "paper"];
+    readonly ease: readonly ["tau-out"];
+    readonly animate: readonly ["hm-pulse"];
+};
+export declare const cn: (...inputs: ClassValue[]) => string;

package/types/packages/ui/src/hooks/fadeScrollClass.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 面板内纵向滚动区类名（桌面端 FadeScroll、Drawer 正文共用）：edge fade 协议 + 内缩滚动条（4px 细条 + 右侧 6px 透明边 +
+ * 轨道上下各 10px，不贴容器边缘）。滚动容器由第三方组件渲染、无法包 <FadeScroll> 时，
+ * 直接挂此类名并对容器调用 useEdgeFade。右侧 6px 透明边算在宽度里，调用方右内边距相应减 6px。
+ * 不用 .scrollbar-inset：它是未分层 CSS，其 4px 轨道边会压过这里的工具类。
+ * 轨道内缩用 margin 而非透明 border：Chromium 的滑块会画进轨道 border，滚到顶/底仍贴边
+ */
+export declare const FADE_SCROLL_CLASS: string;

package/types/packages/ui/src/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./useEdgeFade";
+export * from "./scrollbarAutoHide";
+export * from "./fadeScrollClass";

package/types/packages/ui/src/hooks/isEditableTarget.d.ts

@@ -0,0 +1,2 @@
+/** 键盘操作让位输入框、文本域和可编辑节点。 */
+export declare function isEditableTarget(target: EventTarget | null): boolean;

package/types/packages/ui/src/hooks/lockBodyScroll.d.ts

@@ -0,0 +1 @@
+export declare function lockBodyScroll(owner: Document): () => void;

package/types/packages/ui/src/hooks/scrollbarAutoHide.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 滚动条自动隐藏 —— 事件委托驱动，AppShell 初始化一次、全局滚动区生效。
+ *
+ * 为什么不用纯 CSS（.app *:hover::-webkit-scrollbar-thumb）：Chromium 的滚动条
+ * 伪元素不随 :hover 常规重算，显形后可能冻结不消失。改为 mouseover/scroll/mouseout
+ * 事件给活跃滚动容器切换 scrollbar-live 类（base.css 消费），行为 =
+ * hover 或滚动中显形、停止滚动 700ms 且鼠标不在时隐藏、移出窗口立即隐藏。
+ */
+export declare function initScrollbarAutoHide(owner?: Document): () => void;

package/types/packages/ui/src/hooks/useEdgeFade.d.ts

@@ -0,0 +1,22 @@
+export type ScrollState = {
+    /** 已滚离顶部（scrollTop > 1，1px 容差吸收 DPI 缩放下的取整残留）：顶部渐隐的显示条件 */
+    scrolled: boolean;
+    /** 还能向下滚动（未滚到底）：底部渐隐的显示条件；内容不足一屏时恒为 false */
+    canScrollDown: boolean;
+};
+export type EdgeFadeOptions = {
+    /** 启用顶部渐隐（默认 true） */
+    top?: boolean;
+    /** 启用底部渐隐（默认 true）。末尾内容需要完整可见的页面（无底部留白）可传 false 关掉 */
+    bottom?: boolean;
+};
+/** 滚动边缘状态：scroll 事件 + ResizeObserver（容器尺寸随窗口缩放/侧栏拖宽变化）+
+    MutationObserver（列表数据异步到达撑高内容）三路监听，布尔翻转才 setState。
+    useLayoutEffect 内完成首次测量，避免能滚页面首帧渐隐缺失的闪烁。
+    参数是元素而非 RefObject：视图常有 loading 早退分支（容器晚于首帧挂载），
+    配合 callback ref 的 setState 才能在挂载时重新接线 */
+export declare function useScrollState(el: HTMLElement | null): ScrollState;
+/** 滚动边缘渐隐驱动：把 useScrollState 的结果写为容器 CSS 变量
+    （--edge-top-on / --edge-bottom-on，0 或 1），配合 .home-scroll 的 mask 渐变收放渐隐带。
+    纯 DOM 写变量，不触发额外渲染 */
+export declare function useEdgeFade(el: HTMLElement | null, options?: EdgeFadeOptions): void;

package/types/packages/ui/src/index.d.ts

@@ -0,0 +1,47 @@
+export * from "./cn";
+export { FadeScroll } from "./primitives/FadeScroll";
+export { default as If } from "./primitives/If";
+export { default as ErrorBoundary } from "./primitives/ErrorBoundary";
+export { default as PortalToBody } from "./primitives/PortalToBody";
+export { default as ResizableAndHideableSidebar } from "./primitives/ResizableAndHideableSidebar";
+export { EditText, type EditTextHandle } from "./primitives/EditText";
+export { EDIT_TEXT_PLACEHOLDER } from "./primitives/editTextClasses";
+export * from "./hooks/index";
+export { isEditableTarget } from "./hooks/isEditableTarget";
+export * from "./UiProvider";
+export * from "./primitives/Button";
+export * from "./primitives/IconButton";
+export * from "./primitives/Loading";
+export * from "./primitives/Panel";
+export * from "./primitives/Toast";
+export * from "./primitives/Notification";
+export * from "./primitives/Tooltip";
+export * from "./primitives/Select";
+export * from "./primitives/Menu";
+export * from "./primitives/AnchoredPanel";
+export * from "./primitives/Dialog";
+export * from "./primitives/ConfirmDialog";
+export * from "./primitives/Drawer";
+export * from "./primitives/Popover";
+export * from "./primitives/YearHeatmap";
+export * from "./primitives/input/Input";
+export * from "./primitives/input/Textarea";
+export * from "./primitives/input/NumberInput";
+export * from "./patterns/FormRow";
+export * from "./primitives/Checkbox";
+export * from "./primitives/Switch";
+export * from "./primitives/RadioGroup";
+export * from "./primitives/Radio";
+export * from "./primitives/Segmented";
+export * from "./primitives/FilterPill";
+export * from "./primitives/ResizeHandle";
+export * from "./primitives/Tag";
+export * from "./primitives/ValueDisplay";
+export * from "./primitives/datepicker/DatePicker";
+export * from "./primitives/datepicker/DateRangePicker";
+export * from "./primitives/ImagePreview";
+export * from "./primitives/Tabs";
+export * from "./primitives/FileDropZone";
+export * from "./primitives/LoadingOverlay";
+export { lockBodyScroll } from "./hooks/lockBodyScroll";
+export { mergeRefs } from "./primitives/mergeRefs";

package/types/packages/ui/src/patterns/FormRow.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ⚠️ 占位迁移（未经设计稿评审）：本文件是原 primitives/Input.tsx 中 FormField 的
+ * 原样搬迁，仅为了让既有消费者（database 的 DatabasePanels、样板间）在 Input
+ * 重写后继续编译——「表单字段包装」属于表单范式，正式形态是 ui/patterns 的
+ * FormRow（Field 体系，02 §5.1 规划位：label / 描述 / 错误 / touched 策略 /
+ * ref 聚焦钩子），待出设计稿后整体重做，届时本导出名与 render-props 契约
+ * 均可能变化。在此之前请勿在此基础上加能力。
+ */
+import { type ReactNode } from "react";
+export declare function FormField({ label, description, error, required, children, }: {
+    label: string;
+    description?: string;
+    error?: string | null;
+    required?: boolean;
+    children: (props: {
+        id: string;
+        "aria-describedby"?: string;
+        "aria-invalid"?: boolean;
+    }) => ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/primitives/AnchoredPanel.d.ts

@@ -0,0 +1,53 @@
+/**
+ * AnchoredPanel 基础件 —— 锚定面板：浮层家族的定位基座（Radix Popper 同构层）。
+ *
+ * 与 Popover 的分工：AnchoredPanel 只管锚定定位（D-004 引擎）、卡片视觉、portal
+ * 与显隐过渡——无开合状态（默认锚点在即显示，open 可由宿主驱动）、不监听外点、
+ * 不消费 Esc/Tab、不抢焦点，键盘与焦点事件原样冒泡给宿主仲裁。Popover 组合它并
+ * 叠加交互层（trigger 注入、外点/Esc/Tab 仲裁、焦点契约、dialog 语义）；卡片与
+ * Body/Footer 的视觉形制只有本文件一份。
+ *
+ * 直接使用的场景：浮层是某个交互会话的一部分、生命周期完全由宿主拥有——如行内
+ * 编辑器的选项面板（编辑会话在，面板在；失焦/Esc 由编辑宿主统一判定）。需要独立
+ * 开合的浮层用 Popover，勿直接用此件。
+ */
+import { type HTMLAttributes, type ReactNode, type Ref } from "react";
+import { type AnchoredPlacement } from "./anchoredPosition";
+/** Body 顶部间距按有无头行分流（头行自带 pb）；由带头行的容器（如 Popover）提供 */
+export declare const PanelHasHeaderContext: import("react").Context<boolean | null>;
+export interface AnchoredPanelProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "className"> {
+    /** 锚点元素；为空时不渲染（宿主常在 ref 就绪后再挂） */
+    anchor: HTMLElement | null;
+    /** 12 向全表（引擎 flip/shift 兜底），默认 bottom-start */
+    placement?: AnchoredPlacement;
+    /** 显隐由宿主驱动；缺省锚点存在即显示（宿主托管用法） */
+    open?: boolean;
+    /** 8px 菱形箭头（随 flip 换边），默认关 */
+    arrow?: boolean;
+    /** 透传浮层卡片（宽度控制如 w-[360px]，覆盖 min/max 约束） */
+    className?: string;
+    children: ReactNode;
+    /** 卡片 DOM 引用（AnchoredPanel 内部已占用一位做定位，此处合并外部引用） */
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function AnchoredPanel({ anchor, placement, open, arrow, className, children, ref: externalRef, ...cardProps }: AnchoredPanelProps): import("react").ReactPortal | null;
+export declare namespace AnchoredPanel {
+    var Body: typeof AnchoredPanelBody;
+    var Footer: typeof AnchoredPanelFooter;
+}
+export interface AnchoredPanelBodyProps {
+    children: ReactNode;
+    className?: string;
+}
+/** 正文：独立滚动（上限 min(60vh, 420px)）+ 边缘渐隐 + 透明右边框挤位（D-012 手法，
+ *  浮层滚动区通用口径）；顶部间距按有无头行分流：无头行自足 14px，有头行收敛 10px。
+ *  滚动轨道上下让位（track margin；track 透明边框不缩短 thumb 活动区）：贴浮层边缘的一端
+ *  让出圆角半径，免得 thumb 画进 rounded-tau-lg 的圆角外；头行下方只留 4px */
+declare function AnchoredPanelBody({ children, className }: AnchoredPanelBodyProps): import("react/jsx-runtime").JSX.Element;
+export interface AnchoredPanelFooterProps {
+    children: ReactNode;
+    className?: string;
+}
+/** 应答区：随需——无操作即无 footer；按钮右对齐（主按钮恒在最右） */
+declare function AnchoredPanelFooter({ children, className }: AnchoredPanelFooterProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/types/packages/ui/src/primitives/Button.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Button —— 文字按钮基础件（方案 B「现代产品」形制，mockups/button/，D-013）。
+ *
+ * 变体六档是一个动作的全部音量，层级纪律靠评审不进 API：
+ *  - primary：accent 实心 + 微投影，每屏至多一枚；Dialog 应答区主按钮位
+ *  - secondary：surface 亮底 + line-1 描边（D-007/D-009「浮起物」口径），应答与取消的默认档
+ *  - soft：accent-soft 平底，工具栏高频次级强调（比 secondary 轻、比 ghost 重）
+ *  - ghost：无底 hover 淡墨，与 IconButton 同反馈语言
+ *  - danger / danger-soft：对齐 D-011 危险分级——实心红只给确认位，列表/工具栏一律 soft
+ *
+ * 行为契约：loading = aria-busy + spinner + 文案切换 + 一并 disabled（指针封锁与
+ * Tab 队列退出由原生 disabled 承担）；disabled 同理走原生属性；focus-visible 才显
+ * 焦点环（鼠标点击不显、Tab 才显）；图标仅左位 16px，icon-only 归 IconButton。
+ * 反馈是「光」的（换色 / 边框加深 / brightness），无位移。
+ */
+import type { ComponentProps } from "react";
+import type { LucideIcon } from "lucide-react";
+export type ButtonVariant = "primary" | "secondary" | "soft" | "ghost" | "danger" | "danger-soft";
+export interface ButtonProps extends ComponentProps<"button"> {
+    variant?: ButtonVariant;
+    size?: "sm" | "md";
+    /** 左位图标（16px stroke 1.75）；纯图标按钮走 IconButton，不设 icon-only 档 */
+    icon?: LucideIcon;
+    /** 满宽（空态 CTA / 窄容器） */
+    block?: boolean;
+    /** 载入中：spinner + aria-busy + 文案切换 + disabled，点击不触发 */
+    loading?: boolean;
+    /** loading 时的文案（默认保持 children 不变） */
+    loadingText?: string;
+}
+export declare function Button({ variant, size, icon: Icon, block, loading, loadingText, className, type, disabled, onClick, children, ref, ...props }: ButtonProps): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/primitives/Checkbox.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Checkbox —— 勾选基础件（Input 方案 A「经典描边」语言，mockups/checkbox/，2026-09-19 定稿）。
+ *
+ * 原生 input[type=checkbox] 承载语义（appearance-none 自绘皮）：label 点击切换、
+ * Space 原生支持、读屏语义白送。「浮起物」：16×16 视觉格 surface + line-1，
+ * 选中转 accent 实底 + 反色勾（110ms 淡入，唯一的固定反馈——无动效 prop）。
+ *
+ * 结构铁律：input / 格子 / 勾图标必须在同一层互为兄弟——Tailwind 的 peer-* 变体
+ * 只匹配 peer 的后续兄弟（`~ *`），挂在深层后代上会静默失效（勾选后无任何视觉）。
+ * 状态语义（与 Input 裁决同源）：
+ *  - 命中 24×24（input 绝对定位撑满锚格，宪法下限）；focus-visible 才显 ring
+ *    （锚格经 has- 变体响应，因锚是 input 的父级而非兄弟）
+ *  - hover 描边加深半档（未选中 ink-3/50 / 选中 accent-hover），聚焦时让位
+ *  - indeterminate 半选（accent 实底 + 横线）：DOM 属性驱动，联动逻辑归调用方
+ *  - 错误态正源 aria-invalid（未选中 danger；选中/半选保持 accent）；禁用降透明
+ */
+import { type ComponentProps, type ReactNode } from "react";
+export interface CheckboxProps extends Omit<ComponentProps<"input">, "type"> {
+    /** 可选：渲染关联 label（点文字切换）；不传则裸勾选框 */
+    label?: ReactNode;
+    /** 半选视觉态（DOM 属性驱动；点击行为仍由调用方决定全选/清空） */
+    indeterminate?: boolean;
+}
+export declare function Checkbox({ label, indeterminate, className, disabled, ref, ...props }: CheckboxProps): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/primitives/ConfirmDialog.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ConfirmDialog —— Dialog 的最薄语义预设：确认类对话一句话接线（D-011）。
+ *
+ * 信息一处一责：标题讲动作、context 徽标记对象、description 讲事实、impact 念
+ * 后果、按钮文案不带数量。danger 两档（D-011 用户裁决）：
+ *  - 轻 danger：实心红主按钮 + 初始焦点落取消（回车不误触），一步确认
+ *  - 真·不可逆：typeToConfirm 传对象名，输入匹配才解锁确认按钮（每次打开重置）
+ *
+ * 异步确认两种接法：
+ *  - 推荐：onConfirm 返回 Promise（async 函数天然满足）——自动进入 loading，
+ *    resolve 后自动关闭、reject 保持打开（错误留在原地处理）；loading 态封锁
+ *    一切关闭路径，回执交 Toast（D-003 家族分工）
+ *  - 受控：loading prop 由调用方管理（多步进度等），完成后自行把 open 置 false。
+ *    注意不能在 onConfirm 里才 set loading——props 是渲染快照，同步路径会先按
+ *    false 立即关闭（样板间首版即踩此竞态，故内建 Promise 感知）
+ */
+import { type ReactNode } from "react";
+export interface ConfirmDialogProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    title: string;
+    /** 操作对象（徽标） */
+    context?: string;
+    description?: ReactNode;
+    /** 影响行（后果量化），danger 主按钮时默认走 danger 色 */
+    impact?: string;
+    confirmText?: string;
+    cancelText?: string;
+    /** 主按钮 danger 实心 + 初始焦点落取消（防回车误触） */
+    danger?: boolean;
+    /** 输入该名称后确认按钮才解锁——只给真·不可逆操作（档位不是装饰） */
+    typeToConfirm?: string;
+    critical?: boolean;
+    /** 确认进行中：封锁关闭路径 + 主按钮 loading；onConfirm 返回 Promise 时自动管理 */
+    loading?: boolean;
+    loadingText?: string;
+    onConfirm?: () => void | Promise<unknown>;
+    /** 条件未满足时禁用确认位（如仍在同步），取消照常可用 */
+    confirmDisabled?: boolean;
+    size?: "sm" | "md" | "lg";
+    width?: number;
+    className?: string;
+}
+export declare function ConfirmDialog({ open, onOpenChange, title, context, description, impact, confirmText, cancelText, danger, typeToConfirm, critical, loading, loadingText, onConfirm, confirmDisabled, size, width, className, }: ConfirmDialogProps): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/primitives/Dialog.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Dialog 基础件 —— 模态决策容器 + ConfirmDialog 语义预设（形制与行为裁决见 D-011）。
+ *
+ * 形制：体内大标题 + 上下文徽标（context）+ hairline 应答区（主按钮最右，按钮序列
+ * 由 footer 提供）+ blur 遮罩；长内容滚动区接 edge fade（对齐壳层 useEdgeFade
+ * 协议）。阻断通知不带 icon，文字头部与其它对话同构（D-011）。
+ *
+ * 行为内建（不做成 props）：
+ *  - 开合动效：遮罩淡入 + 卡片 scale(0.97)+translateY(8px)，退场等长后卸载；根上带
+ *    data-morph（视图转场进行中）时一步到位到终态——转场更新期间 rAF 不触发，入场
+ *    动效跑不起来，浏览器要截的是终态。卡片 data-state=open|closed 供形变定位就绪
+ *  - Esc：仅 open 态在卡片 DOM 消费（stopPropagation）——焦点圈闭保证 Esc 必落
+ *    卡片，焦点链即 LIFO，不进 D-003 注册表（同 D-007/D-010 口径，ui 不反向依赖
+ *    page/）；critical 抖动拒绝
+ *  - 关闭矩阵：dismissible = × + Esc + 遮罩点击；critical = 无 ×、遮罩点击抖动；
+ *    locked（异步 loading）= 全失效
+ *  - Tab 圈闭（首尾环绕）· 打开记录触发元素、关闭归还焦点
+ *  - 初始焦点落卡片内 [data-autofocus] 元素（无则卡片自身）；表单场景把
+ *    data-autofocus 放首输入框，danger 场景放取消按钮
+ *  - 打开锁定底层滚动；卡片是限高（78vh）的 flex 列，头尾钉住
+ *
+ * 正文组合（同 MUI DialogContent / Chakra ModalBody）：卡片不替内容决定滚动，
+ * children 原样排在标题与应答区之间。常规正文包 <DialogBody>——它是滚动区
+ * （edge fade + 内缩滚动条 + 标准内边距）；放在 DialogBody 之外的内容自然钉住
+ * 不随正文滚动（元信息行、标签栏等）；工作台型弹窗（双栏树 + 预览等）不用
+ * DialogBody，配合 height 定高由内容自行分栏滚动。
+ *
+ * 自定义头部：`header` 整体替换内建标题行与 ×（工作台型弹窗自带导航头时用），
+ * 关闭入口由 header 自行提供；`title` 仍是对话框的无障碍名称。
+ *
+ * 尺寸档是预设不是牢笼（D-011）：sm 380 / md 440（默认）/ lg 560，width 任意值覆盖；
+ * 高度默认随内容（上限 78vh），height 定高（仍不超 82vh）。
+ * 层级：遮罩容器 z-[340]（Toast 200 < Select/Menu 250 < Tooltip 300 之上）。
+ */
+import { type KeyboardEvent as ReactKeyboardEvent, type ReactNode, type Ref } from "react";
+export interface DialogProps {
+    open: boolean;
+    /** 提前挂载内容，待异步初始化完成后再显示并接管焦点。 */
+    contentReady?: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** 退场完成且内容卸载后调用，可在此清理业务草稿。 */
+    onAfterClose?: () => void;
+    title: string;
+    /** 替换内建标题行与 ×；关闭入口由调用方在 header 内提供，title 转为 aria-label */
+    header?: ReactNode;
+    /** 标题左侧图标（16px、ink-2，随需出现；阻断通知等场景保持纯文字头部） */
+    icon?: ReactNode;
+    /** 标题下的次级说明行（meta 字号，随需出现） */
+    subtitle?: string;
+    /** 操作对象（上下文徽标，随需出现；标题保持动作语义） */
+    context?: string;
+    /** footer 影响行——后果量化贴决策点；impactDanger 走 danger 色 */
+    impact?: string;
+    impactDanger?: boolean;
+    /** critical：无 ×，遮罩/Esc 抖动拒绝——「必须作答」档 */
+    critical?: boolean;
+    /** 关闭路径全封锁（异步进行中，半途关闭即坏文件） */
+    locked?: boolean;
+    size?: "sm" | "md" | "lg";
+    /** 任意宽度（px）覆盖 size——业务特殊版式不必硬凑档位 */
+    width?: number;
+    /** 卡片定高（px，不超 82vh）——工作台型弹窗由内容自管滚动时用，避免高度随内容跳动 */
+    height?: number;
+    /** 应答区按钮序列（主按钮恒在最右；组件自身不渲染按钮） */
+    footer?: ReactNode;
+    children?: ReactNode;
+    /** 卡片 onKeyDown 透传（ConfirmDialog 用它接管 Enter 默认应答） */
+    onKeyDown?: (e: ReactKeyboardEvent<HTMLDivElement>) => void;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function Dialog({ open, contentReady, onOpenChange, onAfterClose, title, header, icon, subtitle, context, impact, impactDanger, critical, locked, size, width, height, footer, children, onKeyDown, className, ref, }: DialogProps): import("react").ReactPortal | null;
+export interface DialogBodyProps {
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * Dialog 正文滚动区：同 FadeScroll 的内缩滚动条（轨道上下各留 10px，不贴头尾），右侧 6px
+ * 透明边、右内边距相应减 6px；只纵向滚动（内容借位负外边距超出时不冒横向滚动条）。
+ * 底部留白按有无应答区取：有则贴 hairline 前留 22px，无则滚动区离卡片底 16px。
+ */
+export declare function DialogBody({ children, className }: DialogBodyProps): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/primitives/Drawer.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Drawer 基础件 —— 右侧抽屉，两种形态共用头部 / 正文 / 开合与内容保留：
+ *
+ * modal（默认）：距视口四边 8px 的浮起卡 + 淡遮罩（不 blur），portal 到 body 级容器。
+ *   Skill / MCP 服务器 / 站点设置等「看完即走」的详情与配置。
+ *   - 开合：遮罩淡入 + 卡片自右缘滑入（280ms），退场后卸载
+ *   - Tab 圈闭 · 打开记录触发元素、卸载归还焦点 · 初始焦点落 [data-autofocus]（无则卡片）
+ *   - 遮罩点击关闭 · 打开锁定底层滚动 · 内部 Select / Menu 继承卡片内的局部 Portal 容器
+ *
+ * modal={false}：就地渲染在最近的定位祖先里（默认 absolute 距上右下 12px），无遮罩、不抢焦点、
+ *   不锁滚动——「边看边改」的伴随面板（待办详情、复习参考资料、白板关联笔记）。
+ *   - 开合：以右缘为原点微缩 + 淡入（240ms），外框始终在容器内，不被纸的圆角裁掉
+ *   - 焦点可能在抽屉外（用户回到列表 / 画布），Esc 需调用方另接页面浮层仲裁
+ *     （桌面端 useOverlayDismiss）；焦点在抽屉内时由抽屉自己消费
+ *
+ * 共同：
+ *  - 结构：头部（前导图标 · 标题 / 副标题 / 元信息三行 · 右侧操作区 + ×）→ 可选 toolbar →
+ *    正文滚动区（FADE_SCROLL_CLASS + edge fade）→ 可选 footer。不传 title 即无头部，× 浮在
+ *    右上角；fill 让正文不滚动、无内边距，内容自管布局（自带头部与滚动的复杂面板）
+ *  - Esc 在抽屉 DOM 消费（stopPropagation）；内层 Select / Menu 先消费自己的 Esc
+ *    （defaultPrevented 让位）；visible 渲染期派生，Activity 保活停驻时必然退到不可见不可点
+ *  - isolateKeyboard：键盘事件在抽屉边界停止冒泡（冒泡阶段，内层编辑器照常收到），
+ *    宿主在 document 上监听快捷键时（白板）用它防串键
+ *  - onWidthChange：左缘出现拖拽调宽手柄，宽度受控、夹在 minWidth / maxWidth 之间
+ *
+ * 退场期间内容保留：抽屉多由「选中项 | null」驱动，关闭即 null 会让内容在滑出途中消失。
+ * 调用方用 useRetainedValue(item) 拿到「最后一次非空值」渲染即可。
+ *
+ * 尺寸档：sm 440 / md 560（默认）/ lg 720，width 任意值覆盖；不超出视口（modal）/ 容器（非模态）。
+ * 层级：modal z-[340]，与 Dialog 同层——后打开者在上；非模态 z-10，className 可覆盖。
+ */
+import { type ReactNode, type Ref } from "react";
+declare const SIZE_WIDTH: {
+    readonly sm: 440;
+    readonly md: 560;
+    readonly lg: 720;
+};
+export interface DrawerProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** 退场完成且内容卸载后调用 */
+    onAfterClose?: () => void;
+    /** false = 非模态伴随面板（见文件头） */
+    modal?: boolean;
+    /** 标题：字符串或自定义节点（如标题 + 来源标签、可编辑标题）；不传则无头部，× 浮在右上角 */
+    title?: ReactNode;
+    /** 无障碍名；title 不是纯字符串（或没有 title）时必填 */
+    label?: string;
+    /** 前导视觉（图标 / 头像 / 勾选框），尺寸由调用方决定，与标题首行顶对齐 */
+    icon?: ReactNode;
+    /** 标题下第二行（meta 字号 ink-3）：字符串单行截断；节点由调用方决定截断 / 折行 */
+    subtitle?: ReactNode;
+    /** 第三行元信息（徽标 + 计数等，sm 字号横排） */
+    meta?: ReactNode;
+    /** 头部右侧操作区（× 之前）：主操作按钮、更多菜单、开关等 */
+    actions?: ReactNode;
+    /** 头部下方、正文之上的钉住条（分区 Segmented、筛选等），不随正文滚动 */
+    toolbar?: ReactNode;
+    /** 底部钉住区（hairline 分隔）：保存提示、应答按钮等 */
+    footer?: ReactNode;
+    /** 正文不滚动、无内边距，flex 列由内容自管（自带头部与滚动的复杂面板） */
+    fill?: boolean;
+    /** 键盘事件不冒泡出抽屉（宿主在 document 上监听快捷键时防串键） */
+    isolateKeyboard?: boolean;
+    size?: keyof typeof SIZE_WIDTH;
+    /** 任意宽度（px）覆盖 size；配合 onWidthChange 即受控宽度 */
+    width?: number;
+    /** 传入即开启左缘拖拽调宽 */
+    onWidthChange?: (width: number) => void;
+    minWidth?: number;
+    maxWidth?: number;
+    /** × 的无障碍名（默认「关闭」） */
+    closeLabel?: string;
+    /** 正文滚动区附加类（改内边距、字号等） */
+    bodyClassName?: string;
+    /** 抽屉卡片附加类（非模态常用来改定位：top-0、z-50 等） */
+    className?: string;
+    children?: ReactNode;
+    ref?: Ref<HTMLElement>;
+}
+export declare function Drawer({ open, onOpenChange, onAfterClose, modal, title, label, icon, subtitle, meta, actions, toolbar, footer, fill, isolateKeyboard, size, width, onWidthChange, minWidth, maxWidth, closeLabel, bodyClassName, className, children, ref, }: DrawerProps): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * 退场期间保留内容：返回 value；value 为空时返回最后一次非空值。
+ * 抽屉由「选中项 | null」驱动时，用它渲染内容，关闭滑出途中不会变空白。
+ */
+export declare function useRetainedValue<T>(value: T | null | undefined): T | null;
+export {};

package/types/packages/ui/src/primitives/EditText.d.ts

@@ -0,0 +1,32 @@
+import React from "react";
+interface IEditTextProps {
+    id?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    defaultValue?: string;
+    value?: string;
+    placeholder?: string;
+    placeholderClassName?: string;
+    placeholderStyle?: React.CSSProperties;
+    contentEditable?: boolean;
+    onChange?: (value: string) => void;
+    onPressEnter?: () => void;
+    onDeleteEmpty?: () => void;
+    defaultFocus?: boolean;
+    onBlur?: () => void;
+    onKeyDown?: (e: KeyboardEvent) => void;
+    isSlateEditor?: boolean;
+}
+export type EditTextHandle = {
+    clear: () => void;
+    setValue: (value: string) => void;
+    focus: () => void;
+    isFocus: () => boolean;
+    focusEnd: () => void;
+    selectAll: () => void;
+    blur: () => void;
+    getValue: () => string;
+    setContentEditable: (editable: boolean) => void;
+};
+export declare const EditText: React.NamedExoticComponent<IEditTextProps & React.RefAttributes<EditTextHandle>>;
+export default EditText;

package/types/packages/ui/src/primitives/ErrorBoundary.d.ts

@@ -0,0 +1,16 @@
+import React from "react";
+interface IErrorBoundaryProps {
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+    onError?(error: Error): void;
+    key?: React.Key;
+}
+interface IErrorBoundaryState {
+    error: string;
+}
+declare class ErrorBoundary extends React.Component<IErrorBoundaryProps, IErrorBoundaryState> {
+    constructor(props: IErrorBoundaryProps);
+    componentDidCatch(error: Error): void;
+    render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null;
+}
+export default ErrorBoundary;