@xiongtao.xt/tau-ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LastKnightCoder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# Tau ui 作者契约
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+通过 npm 别名安装为 `@tau/ui`。运行时由 Tau 桌面宿主提供，构建时必须 external；不可在普通 Node.js 程序中直接执行。
+
+模板与使用说明：https://github.com/LastKnightCoder/tau-plugin-template

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@xiongtao.xt/tau-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LastKnightCoder/editor.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "description": "Tau 桌面开发插件契约；运行时由宿主提供",
+  "exports": {
+    ".": {
+      "types": "./types/packages/ui/src/index.d.ts",
+      "default": "./runtime.js"
+    }
+  },
+  "dependencies": {
+    "@types/react": "19.2.0",
+    "@types/react-dom": "19.2.0",
+    "clsx": "2.1.1",
+    "lucide-react": "0.399.0"
+  },
+  "peerDependencies": {
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  }
 }

package/runtime.js

@@ -0,0 +1 @@
+throw new Error("Tau 插件模块由桌面宿主提供，请在插件构建中设为 external");

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

@@ -0,0 +1,26 @@
+import { type ThemeMode } from "./defineTheme";
+import "./register";
+/** 明暗偏好：固定浅色 / 固定深色 / 跟随系统（与主题族正交） */
+export type Appearance = ThemeMode | "system";
+export declare const DEFAULT_THEME_KEY = "paper";
+export declare const DEFAULT_APPEARANCE: Appearance;
+export declare const THEME_STORAGE_KEY = "tau-theme";
+export declare const APPEARANCE_STORAGE_KEY = "tau-appearance";
+export interface ThemeRuntimeConfig {
+    defaultTheme: string;
+    defaultAppearance: Appearance;
+    themeStorageKey: string;
+    appearanceStorageKey: string;
+    themes: string[];
+}
+export interface ResolvedThemePreference {
+    theme: string;
+    appearance: Appearance;
+    mode: ThemeMode;
+}
+export declare function themeRuntimeConfig(overrides?: Partial<Omit<ThemeRuntimeConfig, "themes">>): ThemeRuntimeConfig;
+/**
+ * 存储值 → 生效主题。首帧内联脚本经 toString() 内嵌本函数，必须自包含（不引用模块内其它符号）。
+ */
+export declare function resolveThemePreference(savedTheme: string | null, savedAppearance: string | null, prefersDark: boolean, config: ThemeRuntimeConfig): ResolvedThemePreference;
+export declare function createThemeBootstrapScript(config?: ThemeRuntimeConfig): string;

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

@@ -0,0 +1,45 @@
+/**
+ * defineTheme 协议 —— 一个文件声明一个主题族的全部。
+ *
+ * 与 definePage 同构的声明式协议（设计见 docs/redesign/02-UI设计系统规范.md §2.2）：
+ *  - 一个主题族 = key/名字 + 浅色、深色两套 palette/tokens 映射函数；深浅都是必填，
+ *    不存在「只有浅色的主题」，明暗是与主题族正交的维度（用户偏好 light/dark/system）；
+ *  - tokens() 返回值被约束为全键 SemanticTokens，漏键 = 编译错误（杜绝补丁式主题）；
+ *  - 派生逻辑（accent hover/soft 等）写在映射函数里，显式可读，不藏在 CSS calc 中；
+ *  - 注册进纯数据注册表；运行时由 theme.ts 切换 data-theme / data-mode。
+ *
+ * 运行时：tokens.css 的 [data-theme][data-mode] 数据块级联取值（index.html 内联脚本首帧
+ * 预置，theme.ts 只切属性 + 持久化），数据块与 tokens() 产物由 theme-parity 测试守护；
+ * 后续优化为构建期 codegen（`pnpm ui:themes` 生成数据块），协议不变。
+ */
+import type { SemanticTokens } from "./tokenContract";
+export type ThemeMode = "light" | "dark";
+export declare const THEME_MODES: readonly ThemeMode[];
+/** 原始色板输入（主题作者自由组织，不进组件；数值型输入用于派生计算） */
+export type ThemePalette = Record<string, string | number>;
+/** 主题族的一套明暗配色 */
+export interface ThemeVariant {
+    palette: ThemePalette;
+    /** 色板 → 语义 token 的纯函数映射产物（全键强制） */
+    tokens: SemanticTokens;
+}
+export interface ThemeDefinition extends Record<ThemeMode, ThemeVariant> {
+    key: string;
+    name: string;
+    /** 设置页等列表中的排序权重（升序，同权重按注册顺序）；缺省 0 */
+    order: number;
+}
+export interface ThemeVariantArgs {
+    palette: ThemePalette;
+    tokens: (p: ThemePalette) => SemanticTokens;
+}
+export interface ThemeDefinitionArgs extends Record<ThemeMode, ThemeVariantArgs> {
+    key: string;
+    name: string;
+    order?: number;
+}
+export declare function defineTheme(args: ThemeDefinitionArgs): ThemeDefinition;
+export declare function getThemeRegistry(): ReadonlyMap<string, ThemeDefinition>;
+/** 按 order 排序的主题列表（供设置页等枚举展示；不依赖注册 / import 顺序） */
+export declare function listThemes(): ThemeDefinition[];
+export declare function getTheme(key: string): ThemeDefinition | undefined;

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

@@ -0,0 +1,10 @@
+/**
+ * 主题契约根入口：token 词汇表、defineTheme 协议与注册表、内置主题、偏好解析与首帧脚本生成。
+ * 纯数据 + 纯函数，不依赖 DOM / React，可在 Node（vite 配置、主进程、测试）中直接使用。
+ * DOM 应用见 `@tau/themes/dom`，React 运行时见 `@tau/themes/react`。
+ */
+import "./register";
+export * from "./tokenContract";
+export { THEME_MODES, defineTheme, getTheme, getThemeRegistry, listThemes } from "./defineTheme";
+export type { ThemeDefinition, ThemeDefinitionArgs, ThemeMode, ThemePalette, ThemeVariant, ThemeVariantArgs, } from "./defineTheme";
+export { APPEARANCE_STORAGE_KEY, DEFAULT_APPEARANCE, DEFAULT_THEME_KEY, THEME_STORAGE_KEY, createThemeBootstrapScript, resolveThemePreference, themeRuntimeConfig, type Appearance, type ResolvedThemePreference, type ThemeRuntimeConfig, } from "./bootstrap";

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

@@ -0,0 +1,9 @@
+/**
+ * 内置主题的副作用注册。各入口 import 本文件，保证取注册表前主题已就位。
+ */
+import "./themes/paper.theme";
+import "./themes/ocean.theme";
+import "./themes/mint.theme";
+import "./themes/wisteria.theme";
+import "./themes/sakura.theme";
+import "./themes/ink.theme";

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

@@ -0,0 +1,11 @@
+/**
+ * 主题「水墨」—— 宣纸落墨：近白而非纯白、近黑而非纯黑，彩度压到最低，素净留白。
+ *
+ * 浅色（宣纸）：微暖米白纸底 + 浓墨；accent 取低饱和「青黛」（墨中带一丝蓝灰），仍是墨色却可辨识；
+ * 状态色取国画颜料（石绿 / 藤黄 / 朱砂 / 花青 / 赭石）并全部降饱和；阴影比其它主题更淡，画面更平静。
+ * 深色（松烟）：暖黑墨底 + 宣纸色墨字 + 提亮青黛；层级口径同暖纸 · 夜。
+ *
+ * 对比度按 02 规范 §2.5，深浅两套均由 theme-parity.test.ts 校验。
+ */
+declare const _default: import("../defineTheme").ThemeDefinition;
+export default _default;

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

@@ -0,0 +1,11 @@
+/**
+ * 主题「薄荷」—— 取自移动端薄荷 Mint（浅色·清新）：灰绿纸底 + 松墨 + 翠绿 accent。
+ *
+ * 浅色（晴）：底色 / 墨色 / 状态色沿用移动端；ink-2 与 accent 按桌面 AA 门禁压深。
+ * 深色（夜林）：移动端无深色版，按同色相推演——墨绿夜底 + 淡薄荷白墨 + 中饱和翠绿 accent；
+ * 绿调强度介于「整页泛绿」与「近中性（与水墨 · 松烟难分）」之间。
+ *
+ * 对比度按 02 规范 §2.5，深浅两套均由 theme-parity.test.ts 校验。
+ */
+declare const _default: import("../defineTheme").ThemeDefinition;
+export default _default;

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;