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

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

@@ -0,0 +1,23 @@
+/**
+ * Switch —— 开关基础件（Input 方案 A 语言，mockups/switch/，2026-09-19 定稿）。
+ *
+ * 语义载体 button[role=switch][aria-checked]：值语义是开/关（对读屏比 checkbox
+ * 准确），Space/Enter 原生切换，focus-visible 才显 ring。
+ *
+ * 形制（「轨道是槽、thumb 是浮起物」，mockups 定稿）：
+ *  - 未选中轨道消费 bg-track（控件轨道语义 token，非表面阶梯——深色主题取
+ *    中调暖棕，亮于 surface 使 thumb 可辨且不显黑；新增主题零组件改动）
+ *  - thumb 恒为 surface 亮底 + ink-3 描边环（在其上清晰分辨），选中后描边
+ *    功成身退（透明）；选中轨道转 accent 实底
+ *  - hover 落在 thumb 描边加深（ink-2），聚焦时让位；拨动 160ms ease-out
+ */
+import { type ComponentProps, type ReactNode } from "react";
+export interface SwitchProps extends Omit<ComponentProps<"button">, "onChange" | "children"> {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onCheckedChange?: (value: boolean) => void;
+    /** 渲染在开关左侧的关联文字（点击切换）；纯读屏标签用 aria-label */
+    label?: ReactNode;
+    size?: "sm" | "md";
+}
+export declare function Switch({ checked: checkedProp, defaultChecked, onCheckedChange, label, size, disabled, className, ...props }: SwitchProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,17 @@
+import { type ReactNode } from "react";
+export interface TabItem<K extends string = string> {
+    key: K;
+    label: ReactNode;
+    children: ReactNode;
+}
+export interface TabsProps<K extends string = string> {
+    items: readonly TabItem<K>[];
+    activeKey?: K;
+    defaultActiveKey?: K;
+    onChange?: (key: K) => void;
+    /** 标签居中（默认左对齐） */
+    centered?: boolean;
+    className?: string;
+}
+/** 下划线式标签页（与 desktop 设置页同一视觉语言）；方向键在标签间移动 */
+export declare function Tabs<K extends string = string>({ items, activeKey: activeKeyProp, defaultActiveKey, onChange, centered, className, }: TabsProps<K>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,24 @@
+/**
+ * Tag —— 值展示标签（A+B 结合 II「点 + 软底」，mockups/tag/plan-ab-dot-soft.html，
+ * 2026-09-19 定稿）。
+ *
+ * soft 底 + 同系 solid 文字（B 的色块扫读）+ 可选 solid 色点（A 的色相焦点）：
+ * 三层同色阶，Notion select 选项标签语感。无色 = 无分类——默认 gray 走
+ * group 底 + ink-2 文字且恒无点。纯展示 span：非交互、无命中要求；
+ * onRemove 数据驱动显 ×（button + aria-label，伪元素把热区扩到 24、
+ * focus-visible 才显 ring、点击不冒泡——表格行点击不受牵连）。
+ *
+ * 单尺寸（高 22、字 tau-sm）无档；长文本 truncate 由容器约束 max-width。
+ */
+import type { ComponentProps } from "react";
+export declare const TAG_COLORS: readonly ["red", "orange", "yellow", "green", "gray", "blue", "purple"];
+export type TagColor = (typeof TAG_COLORS)[number];
+export interface TagProps extends Omit<ComponentProps<"span">, "color"> {
+    /** 分类色（7 色板，与 ColorSwatch 同源）；语义状态复用色板，不另设 status */
+    color?: TagColor;
+    /** 色相焦点（默认开）；gray 恒无点——无色 = 无分类 */
+    showDot?: boolean;
+    /** 传了才渲染移除钮 ×（热区 24，点击不冒泡） */
+    onRemove?: () => void;
+}
+export declare function Tag({ color, showDot, onRemove, className, children, ...props }: TagProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,67 @@
+/**
+ * Toast 基础件 —— 轻量内联胶囊。
+ *
+ * 单行胶囊：类型语义色只落图标（ok/danger/warn/info，深浅主题同构），一句话 +
+ * 可选动作；无关闭钮——整条点击关闭（Sonner 惯例），悬停冻结自动关闭，
+ * 同一位置上限 4 条（挤掉最老）。
+ * 位置四选一：top-center（默认）/ top-right / bottom-right / bottom-center，
+ * 全局默认可经 toast.config 调整、单条可覆写；层级 z-[200]，高于命令面板
+ * （z-[101]），搜索报错等反馈在面板打开时仍可见。不接 Esc（浮层退场注册表
+ * 只登记阻断后退的浮层，见 D-003）。
+ *
+ * 用法：app 壳层挂载 <ToastHost /> 一次；任意处调用 toast.success("已保存")、
+ * toast.error("失败")、toast.loading → toast.resolve(id) 或 toast.promise(p, {...})。
+ */
+export type ToastType = "success" | "error" | "warning" | "info" | "loading";
+export type ToastPosition = "top-center" | "top-right" | "bottom-right" | "bottom-center";
+export interface ToastOptions {
+    /** 内联动作（如「撤销」），点击后 toast 关闭 */
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+    position?: ToastPosition;
+    /** 落定后的停留毫秒数；0 = 落定后也常驻（只靠点击关闭）。载入中恒常驻，与本值无关 */
+    duration?: number;
+}
+/**
+ * 单条胶囊（受 item 驱动的纯展示件）。导出供样板间（src/showcase）构造
+ * duration=0 的常显标本——产品代码仍应只消费 toast 命令式 API 与 ToastHost。
+ */
+export interface ToastItem {
+    id: number;
+    type: ToastType;
+    message: string;
+    action?: ToastOptions["action"];
+    position: ToastPosition;
+    duration: number;
+}
+declare const defaults: {
+    position: ToastPosition;
+    duration: number;
+};
+export declare const toast: {
+    /** 调整全局默认（位置 / 时长） */
+    config(patch: Partial<typeof defaults>): void;
+    show(type: ToastType, message: string, opts?: ToastOptions): number;
+    success(message: string, opts?: ToastOptions): number;
+    error(message: string, opts?: ToastOptions): number;
+    warning(message: string, opts?: ToastOptions): number;
+    info(message: string, opts?: ToastOptions): number;
+    /** 载入中常驻；结束后 resolve（转成功）或 reject（转失败），落定起按 duration 收尾 */
+    loading(message: string, opts?: ToastOptions): number;
+    resolve(id: number, message?: string): void;
+    reject(id: number, message?: string): void;
+    dismiss(id?: number): void;
+    /** promise 形态：loading → 成功/失败（文案支持按结果取值） */
+    promise<T>(promise: Promise<T>, messages: {
+        loading: string;
+        success?: string | ((data: T) => string);
+        error?: string | ((err: unknown) => string);
+    }, opts?: ToastOptions): Promise<T>;
+};
+export declare function ToastHost(): import("react/jsx-runtime").JSX.Element;
+export declare function ToastPill({ item }: {
+    item: ToastItem;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,40 @@
+/**
+ * Tooltip 基础件 —— Portal + 自研 JS mini 定位引擎（选型与排除记录见 D-004）。
+ *
+ * Portal（body 追加 fixed 元素）+ 自研 mini 定位引擎（D-004；定位生命周期收口
+ * useAnchoredPosition，箭头复用 FloatingArrow——D-014 四家共用底盘），中间件链：
+ * offset（间距 8）→ flip（主轴放不下翻对侧）→ shift（交叉轴夹回视口，边距 8）→
+ * arrow（锚点中心在边缘上的投影，两端各留 10px）。
+ *
+ * 行为内建（不做成 props）：hover intent（450ms 进入 / 移出即隐 / 400ms 内重开免延迟——
+ * 相邻触发器快速扫过不重复等待）；focus-visible 显示；aria-describedby 自动接线；
+ * disabled 子元素自动包 wrapper（pointer 事件被吞）；锚点位置变化时 rAF 跟随（动态锚，
+ * 如趋势图 hover 热区随鼠标移动）；scroll(capture)/resize 重算。
+ * 反相配色复用 bg-ink-1 / text-ink-inverse（深浅主题各自反相，对比度由 token 保障）。
+ * 不接 Esc、不进浮层退场注册表（瞬态非阻断，同 Toast 的 D-003 口径）；
+ * 不承载可交互内容——可点的说明浮层是 Popover/Menu 的职责。
+ */
+import { type ReactElement, type ReactNode } from "react";
+import { type AnchoredAlign, type AnchoredPlacement, type AnchoredSide } from "./anchoredPosition";
+/** 引擎类型的历史名（D-004 起对外暴露；D-014 引擎更名后保留别名，存量引用不动） */
+export type TooltipPlacement = AnchoredPlacement;
+export type TooltipSide = AnchoredSide;
+export type TooltipAlign = AnchoredAlign;
+export interface TooltipProps {
+    content: ReactNode;
+    placement?: TooltipPlacement;
+    /** 箭头（默认开；8px 菱形，尖端单角 2.5px 圆角，随 flip 自动换边） */
+    arrow?: boolean;
+    /** 显示延迟毫秒（默认 450；400ms 内重开免延迟） */
+    delay?: number;
+    /** 暂停提示并清理内部打开状态与延迟；优先于 open，不影响子元素交互。 */
+    disabled?: boolean;
+    /** 受控模式（对齐 §5.3 浮层 open 契约）：传入后组件不再做 hover intent，由调用方管理 */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** 触发器（克隆注入事件与 aria-describedby；disabled 元素自动包 wrapper） */
+    children: ReactElement;
+    /** 浮层追加类名（经 cn 合并，可覆盖层级等默认值，如编辑器悬浮工具条之上的 z-[10110]） */
+    className?: string;
+}
+export declare function Tooltip({ content, placement, arrow, delay, disabled, open: openProp, onOpenChange, children, className, }: TooltipProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,25 @@
+/**
+ * ValueDisplay —— 值展示件（占位迁移合集）：ColorSwatch / ProgressBar / Rating。
+ * Tag 已按设计稿定稿拆出 primitives/Tag.tsx（2026-09-19）；本文件剩余三件
+ * 仍是未经设计稿评审的占位实现（ValueDisplay 族逐件定稿时迁出），勿在
+ * 此基础上加能力。
+ */
+import { type TagColor } from "./Tag";
+export declare function ColorSwatch({ value, onChange, disabled, }: {
+    value: TagColor;
+    onChange: (value: TagColor) => void;
+    disabled?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function ProgressBar({ value, max, label, }: {
+    value: number;
+    max?: number;
+    label: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function Rating({ value, onValueChange, max, step, readOnly, label, }: {
+    value: number | null;
+    onValueChange?: (value: number | null) => void;
+    max?: number;
+    step?: 0.5 | 1;
+    readOnly?: boolean;
+    label?: string;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,15 @@
+/**
+ * 全年活动热力图（圆点）—— 今日页回顾段的自绘图表
+ * （圆点、色阶随 scale 递增、周列贴底对齐、hover 呼吸、全宽自适应；
+ * 图例含连续活跃天数角标）。
+ * 零业务依赖：输入为 {date, count}[] 纯数据；色阶为 accent 的 alpha 派生，随主题换肤。
+ */
+import { type ReactNode } from "react";
+export interface YearHeatmapDay {
+    date: string;
+    count: number;
+}
+export declare function YearHeatmap({ days, caption }: {
+    days: YearHeatmapDay[];
+    caption?: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,44 @@
+/**
+ * 浮层定位引擎（Tooltip / Select / Menu / Popover 共用，D-004；D-014 起更名
+ * anchoredPosition——四家消费后不再顶着 tooltip 专名）——不依赖 React，可单独单测。
+ * 中间件链：offset（间距默认 8）→ flip（主轴放不下翻对侧）→ shift（夹回视口，边距 8）→
+ * arrow（锚点中心在边缘上的投影，两端各留 10px）。
+ * 独立成文件：组件文件只导出组件（react-refresh 约束）。
+ *
+ * shift 的闸门：**锚点与视口不相交时完全不夹**。无条件夹会让锚点滚出视口后浮层
+ * 被强行钉在视口边缘、与锚点脱钩——一屏多个离屏锚点就全挤在同一条边上。锚点
+ * 离屏时让它自然跟随锚点离屏即可——几何上就不可见，无需额外的显示态管理。
+ */
+export type AnchoredSide = "top" | "right" | "bottom" | "left";
+export type AnchoredAlign = "start" | "center" | "end";
+export type AnchoredPlacement = AnchoredSide | `${AnchoredSide}-${AnchoredAlign}`;
+/** 引擎可选参数：gap 覆写与锚点的间距（Select/Menu 下拉用 4，Tooltip/Popover 用默认 8）。 */
+export interface AnchoredPositionOptions {
+    gap?: number;
+}
+export interface AnchoredPosition {
+    x: number;
+    y: number;
+    side: AnchoredSide;
+    arrowX: number | null;
+    arrowY: number | null;
+}
+/**
+ * anchor 为触发器矩形；pop 只需要尺寸（jsdom 可用普通对象伪造）。
+ */
+export declare function computeAnchoredPosition(anchor: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}, pop: {
+    offsetWidth: number;
+    offsetHeight: number;
+}, placement: AnchoredPlacement, opts?: AnchoredPositionOptions): AnchoredPosition;
+/**
+ * 引擎投影值 → 箭头 inline 定位。箭头须为浮层的 firstElementChild（含箭头时）；
+ * 每条边都显式写入（另一侧置 auto），side 翻转后不留上一姿态的残留。
+ */
+export declare function applyArrowPosition({ side, arrowX, arrowY }: AnchoredPosition, pop: HTMLElement): void;

package/types/packages/ui/src/primitives/datepicker/DatePicker.d.ts

@@ -0,0 +1,71 @@
+/**
+ * DatePicker 基础件 —— 经典月历单日期（A+ 形态，mockups/datepicker/）。
+ *
+ * 值形状拆分的单日期侧：value: string | null（"YYYY-MM-DD"，precision="minute"
+ * 时 "YYYY-MM-DD HH:mm"）；范围归 DateRangePicker（同一引擎，别在此加 range）。
+ *
+ * 分层（同 Popover/AnchoredPanel）：DatePickerPanel 是可独立使用的内嵌面板
+ * （受控显示 + onCommit 确定，块级渲染，无开合无定位——宿主托管场景直接用它，
+ * 如行内编辑器浮层）；DatePicker = 触发器 + 开合 + 定位 + 外点仲裁 + Panel。
+ *
+ * 行为内建（不做成 props）：
+ *  - 提交模型跟着 precision 走：day 点日期即提交；minute 点日期只挂起，
+ *    底栏时刻区（TimeField：自由键入 + 步长网格）+「确定」显式提交——带时间的
+ *    值改起来贵，不做即点即定；预设（presets）取值即完整，一律即点即定
+ *  - 钻取导航：点标题 days → months → 年代（12 格），‹ › 步长随视图换
+ *  - 键盘全表：触发器 ↑↓·Enter 开面板；面板内方向键 / PgUp·PgDn 翻月 / T 今天 /
+ *    Enter 提交；Esc 逐层退场（时刻网格先收，再关面板），焦点归还触发器
+ *  - 定位复用 D-004 引擎（bottom + gap 4，flip 跟随）；外点关闭（useLayerDismiss）；
+ *    层级 z-[250] 与 Select/Menu 同层
+ *  - 预设行显示在日历下方：presets 数据驱动（label + 取值函数），内容与措辞
+ *    归使用方，组件不内置业务词表；当前值命中时该 chip 高亮回显
+ */
+import { type ReactNode, type Ref } from "react";
+import { type DatePrecision } from "./calendarEngine";
+export type { DatePrecision } from "./calendarEngine";
+export interface DatePickerPreset {
+    label: ReactNode;
+    /** 调用时求值（"今天"这类动态日期每次打开都新鲜）；返回 null 表示清空 */
+    value: () => string | null;
+}
+export interface DatePickerPanelProps {
+    /** 受控显示值（"YYYY-MM-DD" / "YYYY-MM-DD HH:mm"） */
+    value: string | null;
+    /** 确定提交：day 点日期 / minute 确定 / 预设 / 今天 / 清空 */
+    onCommit: (value: string | null) => void;
+    precision?: DatePrecision;
+    presets?: readonly DatePickerPreset[];
+    timeStep?: number;
+    disabled?: boolean;
+    /** 禁用日期谓词（入参 "YYYY-MM-DD"，业务侧零 Date 依赖） */
+    isDateDisabled?: (day: string) => boolean;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function DatePickerPanel({ value, onCommit, precision, presets, timeStep, disabled, isDateDisabled, className, ref, }: DatePickerPanelProps): import("react/jsx-runtime").JSX.Element;
+export interface DatePickerProps {
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (value: string | null) => void;
+    /** 值粒度：day（默认，"YYYY-MM-DD"）| minute（"YYYY-MM-DD HH:mm"，底栏时刻区 + 确定提交） */
+    precision?: DatePrecision;
+    /** 预设行（日历下方）：数据驱动，即点即定 */
+    presets?: readonly DatePickerPreset[];
+    placeholder?: string;
+    size?: "sm" | "md";
+    /** 触发器 hover 浮出清除（值回 null） */
+    clearable?: boolean;
+    /** 禁用日期谓词（入参 "YYYY-MM-DD"，业务侧零 Date 依赖） */
+    isDateDisabled?: (day: string) => boolean;
+    /** 时刻网格步长（分钟），默认 15 */
+    timeStep?: number;
+    disabled?: boolean;
+    /** Field 体系错误态（danger 描边） */
+    status?: "error";
+    /** 浮层受控（§5.3 契约；样板间常显标本用它） */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    className?: string;
+    ref?: Ref<HTMLButtonElement>;
+}
+export declare function DatePicker({ value: valueProp, defaultValue, onValueChange, precision, presets, placeholder, size, clearable, isDateDisabled, timeStep, disabled, status, open: openProp, onOpenChange, className, ref, }: DatePickerProps): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/primitives/datepicker/DateRangePicker.d.ts

@@ -0,0 +1,70 @@
+/**
+ * DateRangePicker 基础件 —— 范围形态（B 形态并入，mockups/datepicker/ 方案 B）。
+ *
+ * 值形状拆分的范围侧：value: readonly [string, string] | null（两端均
+ * "YYYY-MM-DD"，precision="minute" 时为 "YYYY-MM-DD HH:mm"；升序，逆序输入按升序读取）。与 DatePicker 同一引擎（CalendarPanel/弹层契约/触发器皮），
+ * 收起预设列与底栏、去掉 range 即回到单日期形态——不是第二个日历，是同一结构的
+ * 范围扩展态。
+ *
+ * 分层（同 DatePicker/DatePickerPanel）：DateRangePickerPanel 是可独立使用的
+ * 内嵌面板（受控显示 + onCommit 确定，块级渲染，无开合无定位——宿主托管场景
+ * 直接用它）；DateRangePicker = 触发器 + 开合 + 定位 + 外点仲裁 + Panel。
+ *
+ * 行为内建（不做成 props）：
+ *  - 提交模型：手选范围走「点起点 → 悬停预览 → 点终点（自动交换）→ 确定」三道闸
+ *    （范围错一格就触发下游重查询，不做即点即定）；预设即选即定
+ *  - 双月并排（跨月范围不翻页）：左 ‹ 右 › 承载翻月，中间 line-2 弱分隔；
+ *    界外日隐藏，同一天不会在两个面板重复出现
+ *  - minute 精度：两月下方各一个时刻区（左开始 / 右结束），同日结束早于开始时禁止确定
+ *  - 用色纪律：端点 accent 实底、中段 accent-soft，色彩表意不装饰
+ *  - 底栏摘要（"9月12日 – 9月19日 · 共 8 天"）是提交前最后一眼确认
+ *  - 键盘：Enter 确定 / Esc 放弃预览并关闭（焦点归还触发器）
+ */
+import { type Ref } from "react";
+import { type DatePrecision } from "./calendarEngine";
+export interface DateRangePreset {
+    label: string;
+    /** 调用时求值（"本周"这类动态范围每次打开都新鲜）；返回 null 表示清空 */
+    range: () => readonly [string, string] | null;
+}
+export interface DateRangePickerPanelProps {
+    /** 受控显示值（两端按 precision 的值串，升序） */
+    value: readonly [string, string] | null;
+    /** day 只选日期；minute 追加开始/结束时刻区。默认 day */
+    precision?: DatePrecision;
+    /** 时刻网格步长（分钟），默认 15 */
+    timeStep?: number;
+    /** 确定提交：手选「确定」/ 预设即点即定 / 清空 */
+    onCommit: (value: [string, string] | null) => void;
+    /** 面板当前展示的区间（含未确定的草稿）变化时回调；只选了起点时终点为 "" */
+    onPreviewChange?: (value: readonly [string, string] | null) => void;
+    presets?: readonly DateRangePreset[];
+    disabled?: boolean;
+    /** 禁用日期谓词（入参 "YYYY-MM-DD"，业务侧零 Date 依赖） */
+    isDateDisabled?: (day: string) => boolean;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function DateRangePickerPanel({ value: valueProp, onCommit, onPreviewChange, precision, timeStep, presets, disabled, isDateDisabled, className, ref, }: DateRangePickerPanelProps): import("react/jsx-runtime").JSX.Element;
+export interface DateRangePickerProps {
+    value?: readonly [string, string] | null;
+    defaultValue?: readonly [string, string] | null;
+    onValueChange?: (value: [string, string] | null) => void;
+    /** day 只选日期；minute 追加开始/结束时刻区。默认 day */
+    precision?: DatePrecision;
+    /** 时刻网格步长（分钟），默认 15 */
+    timeStep?: number;
+    /** 预设列（面板左列）：数据驱动，即选即定 */
+    presets?: readonly DateRangePreset[];
+    placeholder?: string;
+    size?: "sm" | "md";
+    clearable?: boolean;
+    isDateDisabled?: (day: string) => boolean;
+    disabled?: boolean;
+    status?: "error";
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    className?: string;
+    ref?: Ref<HTMLButtonElement>;
+}
+export declare function DateRangePicker({ value: valueProp, defaultValue, onValueChange, precision, timeStep, presets, placeholder, size, clearable, isDateDisabled, disabled, status, open: openProp, onOpenChange, className, ref, }: DateRangePickerProps): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/primitives/datepicker/calendarEngine.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 日历引擎 —— DatePicker / DateRangePicker 共享的纯函数层。
+ *
+ * 值协议（string，不外泄 Date 对象）：
+ *  - precision="day"     → "YYYY-MM-DD"
+ *  - precision="minute"  → "YYYY-MM-DD HH:mm"
+ * 解析一律本地时区并做回读校验（"2026-02-31" 这类越界串返回 null，不静默滚动）。
+ * 六周固定 42 格：面板高度不随月跳变，界外日参与导航与点选（跨月自动接管视图）。
+ */
+export declare const WEEKDAY_LABELS: readonly ["一", "二", "三", "四", "五", "六", "日"];
+export declare const WEEKDAY_NAMES: readonly ["日", "一", "二", "三", "四", "五", "六"];
+export type DatePrecision = "day" | "minute";
+export declare function toDateKey(date: Date): string;
+/** "YYYY-MM-DD" → 本地 Date（当天 00:00）；格式不符或日历上不存在的日期返回 null */
+export declare function parseDateKey(key: string): Date | null;
+export declare function formatValue(date: Date, precision: DatePrecision): string;
+/** 接受两种精度的值串；带无效时刻的 minute 串按 day 落（时刻归一化见 normalizeTimeInput） */
+export declare function parseValue(value: string): Date | null;
+export declare function sameDay(a: Date, b: Date): boolean;
+export declare function addDays(date: Date, n: number): Date;
+export declare function addMonths(date: Date, n: number): Date;
+/** 周一起始的当周周一 */
+export declare function startOfWeekMonday(date: Date): Date;
+/** 某月的六周固定网格（周一起始；首尾补界外日，inMonth 标记界内） */
+export declare function monthCells(year: number, monthIndex: number): {
+    date: Date;
+    key: string;
+    inMonth: boolean;
+}[];
+/**
+ * 时刻归一化："9" → "09:00"、"9:5" → "09:05"、"09:05" 直映（中文冒号兼容）；
+ * 越界（时 >23 / 分 >59）或非数字返回 null。
+ */
+export declare function normalizeTimeInput(text: string): string | null;
+/** 一天的时刻网格刻度（step 分钟，默认 15）："00:00"、"00:15" … "23:45" */
+export declare function timeGridValues(step?: number): string[];
+/** 时刻 → 网格最近刻度（"10:37" 步长 15 → "10:30"）；值不在步长上时网格无命中格 */
+export declare function nearestStep(time: string, step?: number): string;
+/** 触发器显示格式："2026年9月19日"（minute 追加 " 15:00"） */
+export declare function formatDisplay(value: string): string;
+/**
+ * 范围显示格式：同年省年份（"9月12日 – 9月19日"），跨年两端补全；
+ * minute 值追加时刻，同日只写一次日期（"9月12日 09:00 – 18:00"）
+ */
+export declare function formatRangeDisplay(start: string, end: string): string;

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

@@ -0,0 +1 @@
+export declare const EDIT_TEXT_PLACEHOLDER = "data-[empty=true]:before:content-[attr(data-placeholder)] before:absolute before:left-0 before:top-0 before:w-full before:pointer-events-none before:select-none before:whitespace-pre-wrap before:text-[var(--placeholder-color,var(--tau-ink-3))]";

package/types/packages/ui/src/primitives/input/Input.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Input —— 文本输入基础件（方案 A「经典描边」，mockups/input/，2026-09-19 定稿）。
+ *
+ * 形制：surface 亮底 + line-1 描边 + radius-sm——「浮起物」语感（2026-09-17 表单
+ * 控件口径），与 Select / DatePicker 触发器同族同皮；focus = accent 描边 + 3px ring。
+ * 原生 input 零样式透传（IME / autofill / 无障碍白送），形制挂容器上。
+ *
+ * 状态语义：
+ *  - 错误态正源是原生 aria-invalid（无 status prop）：容器经 has- 变体换 danger
+ *    描边 / danger-soft ring——视觉与读屏语义锁死在同一属性上；判定（zod）与
+ *    错误文案（Field 体系框外）、touched 策略都归表单层
+ *  - 只读：框在、精气神收掉——readOnly 透传后文字转 ink-2、光标 default、
+ *    hover/focus 零响应（仍可选中复制）；禁用 = 原生 disabled + 整体降透明
+ *
+ * 槽位：lead 前缀 icon（16px lucide，focus 转 accent-text）+ clearable 清空 ×
+ * （容器 hover/focus 且有值时显现——visibility:hidden 不响应自身 hover，挂容器；
+ * tabIndex=-1 不抢 Tab 流，清空后焦点留在输入框）。
+ * 文本后缀 / addon 组合等装备位归后续裁决（mockups 方案 D），不预置。
+ */
+import { type ComponentProps } from "react";
+import type { LucideIcon } from "lucide-react";
+export interface InputProps extends Omit<ComponentProps<"input">, "size"> {
+    /** 前缀 icon（16px lucide；focus 时转 accent-text） */
+    lead?: LucideIcon;
+    /** 有值时容器 hover/focus 显现清空 ×；点击清空并保留焦点 */
+    clearable?: boolean;
+    size?: "sm" | "md";
+    /** 形态：outlined（默认，亮底描边浮起物）| bare（无皮行内形态——无边框背景与
+     *  focus 反馈，高度与选中表现归宿主，如行内编辑单元格） */
+    variant?: "outlined" | "bare";
+    /** 外框容器的类名（默认 w-full 撑满）：定宽 / flex 伸缩等布局写这里；
+     *  className 落到内部 <input>（文字对齐、字号等） */
+    wrapperClassName?: string;
+}
+export declare function Input({ lead: Lead, clearable, size, variant, className, wrapperClassName, onChange, defaultValue, ref, ...props }: InputProps): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/primitives/input/NumberInput.d.ts

@@ -0,0 +1,25 @@
+/**
+ * NumberInput —— 数值输入（Input 同形 + beforeinput 事前拦截，mockups/input/ 方案 A）。
+ *
+ * 值契约：value: number | null（string 草稿只在内部，blur/Enter 归一化提交）。
+ *
+ * 事前拦截（2026-09-19 用户裁决，取代「事后标红」）：
+ *  - 原生 beforeinput 监听用「当前值 + 选区 + 待插入文本」预判结果，不合数字格式直接
+ *    preventDefault——键盘输入 / 粘贴 / 拖放的非数字内容根本进不来
+ *  - 粘贴含杂质不生硬拒绝：先清洗（"¥1,200" → "1200"）再以 setRangeText 插入，
+ *    实在洗不干净才放弃（静默，无红字）
+ *  - 合法中间态（"5." / "-."）放行，否则没法输小数；IME 组合期间放行
+ *    （insertCompositionText 不可取消），compositionend 兜底清洗
+ *  - blur / Enter 归一化："5." → 5、".5" → 0.5、去多余前导零
+ */
+import { type ComponentProps } from "react";
+export interface NumberInputProps extends Omit<ComponentProps<"input">, "value" | "defaultValue" | "onChange" | "type" | "size"> {
+    value: number | null;
+    onValueChange: (value: number | null) => void;
+    size?: "sm" | "md";
+    /** 形态透传 Input：bare 为无皮行内形态（无边框背景与 focus 反馈，归宿主） */
+    variant?: "outlined" | "bare";
+    /** 透传 Input：外框容器类名（定宽写这里；className 落到内部 <input>） */
+    wrapperClassName?: string;
+}
+export declare function NumberInput({ value, onValueChange, variant, onBlur, onKeyDown, ref, ...props }: NumberInputProps): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/primitives/input/Textarea.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Textarea —— 多行文本输入（与 Input 同形，mockups/input/ 方案 A）。
+ *
+ * 与 Input 共用形制语言（surface + line-1 + focus ring）；差异只有三点：
+ * 多行布局、纵向起始对齐、maxLength 传值时右下角自动出计数器
+ * （超限转 danger——超限即不可再输，计数是唯一提示，安静而确定）。
+ * 错误态同样走原生 aria-invalid（视觉与读屏同源），文案归 Field 体系。
+ */
+import { type ComponentProps } from "react";
+export interface TextareaProps extends ComponentProps<"textarea"> {
+    /** 传值即在右下角渲染计数器（n / maxLength，超限转 danger） */
+    maxLength?: number;
+}
+export declare function Textarea({ className, onChange, defaultValue, maxLength, rows, ...props }: TextareaProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,6 @@
+import type { Ref } from "react";
+/**
+ * ref 合并 —— 克隆注入触发器时的标准件：调用方已有的 ref（回调或对象两种形态）
+ * 与组件内部的锚 ref 同时接收元素，谁都不被覆盖。Tooltip / Menu / Select / Popover 共用。
+ */
+export declare function mergeRefs<T>(...refs: Array<Ref<T> | undefined>): (el: T | null) => void;