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

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

@@ -0,0 +1,18 @@
+import { type ReactNode, type Ref } from "react";
+interface FadeScrollProps {
+    className?: string;
+    children?: ReactNode;
+    /** 需要拿到滚动容器时用（虚拟列表的 getScrollElement、滚动监听）；对象 ref 或回调 ref */
+    scrollRef?: Ref<HTMLDivElement | null>;
+    /** 内部有 motion 布局动画时开启：渲染为 motion.div 并声明 layoutScroll，动画按滚动偏移校正 */
+    layoutScroll?: boolean;
+    /** 关掉顶部渐隐（默认开）：滚动区顶部紧邻实底工具栏时，渐隐带落在实底上只会显脏 */
+    topFade?: boolean;
+}
+/**
+ * 面板内的纵向滚动区：接 edge fade（对齐壳层 useEdgeFade 协议），只在可滚方向渐隐，
+ * 内容不贴着面板边缘被硬切；滚动条内缩不贴右缘。右侧 6px 透明边算在宽度里，
+ * 调用方右内边距相应减 6px；类名经 cn 合并，调用方可覆盖透明边宽度（如 border-r-[3px]）。
+ */
+export declare function FadeScroll({ className, children, scrollRef, layoutScroll, topFade, }: FadeScrollProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+export interface FileDropZoneProps {
+    /** 同 <input accept> */
+    accept?: string;
+    /** 单选：只取第一个文件 */
+    onFile?: (file: File) => void;
+    /** 多选：拖入或选择的全部文件（同时开启文件框多选） */
+    onFiles?: (files: File[]) => void;
+    disabled?: boolean;
+    className?: string;
+    children: ReactNode;
+}
+/** 点击选择或拖入文件的区域；拖入时高亮 */
+export declare function FileDropZone({ accept, onFile, onFiles, disabled, className, children, }: FileDropZoneProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,19 @@
+/**
+ * 筛选 pill：页面工具栏里的单选筛选项（分类 / 来源 / 状态 / 卡组），可带图标与计数。
+ * 选中 = selected 底 + accent 字；未选有两种皮肤：outline = line-1 描边，raised = surface 底 + 卡片投影。
+ * 选中与否由调用方受控，本组件只报点击；className 经 cn 合并，可覆盖未选中的文字色（如警示）。
+ */
+import type { ReactNode } from "react";
+export interface FilterPillProps {
+    active: boolean;
+    onClick(): void;
+    label: string;
+    /** 不传即不渲染 */
+    count?: number;
+    /** 标签前的图标（调用方自定尺寸与间距） */
+    icon?: ReactNode;
+    /** 未选中的皮肤，默认 outline */
+    variant?: "outline" | "raised";
+    className?: string;
+}
+export declare function FilterPill({ active, onClick, label, count, icon, variant, className, }: FilterPillProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,6 @@
+/**
+ * 图标按钮 —— 30px 方形无底幽灵按钮，hover 淡墨（A2 反馈语言）。
+ * 尺寸/位置微调用 className 覆盖（如侧栏头 27px）。
+ */
+import type { ComponentProps } from "react";
+export declare function IconButton({ className, type, ...props }: ComponentProps<"button">): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,6 @@
+import React from "react";
+interface IIfProps {
+    condition: boolean;
+}
+declare const If: React.FC<React.PropsWithChildren<IIfProps>>;
+export default If;

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

@@ -0,0 +1,16 @@
+import type { ComponentType } from "react";
+export declare function ImagePreview({ images, index, onIndexChange, open, onOpenChange, ImageComponent, }: {
+    images: readonly {
+        src: string;
+        alt?: string;
+    }[];
+    index: number;
+    onIndexChange: (index: number) => void;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    ImageComponent?: ComponentType<{
+        src: string;
+        alt: string;
+        className?: string;
+    }>;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,18 @@
+/**
+ * 加载态 —— Spinner 圆环 + 页面级居中版式（02 §5.1 词表的 Spinner 归位）。
+ * Spinner 可单独行内使用；Loading 铺满父容器居中。
+ *
+ * 兜底高度走 prop（inline style）而非 Tailwind 类（2026-09-17 修正）：原实现把
+ * `min-h-[45vh]` 写死在基础类里，调用方传 `className="min-h-0"` 会被它压掉——
+ * 同名 utility 的胜负由 Tailwind 生成顺序决定，**不由 class 书写顺序决定**，所以
+ * 那个覆盖一直是静默失效的（样板间把 Loading 放进 168px 演示框时内容被裁空，
+ * 才暴露出这个潜在缺陷）。改成 prop 后 inline style 可靠压过任意类。
+ */
+import type { ComponentProps } from "react";
+export declare function Spinner({ className, ...props }: ComponentProps<"span">): import("react/jsx-runtime").JSX.Element;
+export declare function Loading({ label, className, minHeight, }: {
+    label?: string;
+    className?: string;
+    /** 无高度链时的兜底最小高度（默认 45vh）；调用方自带高度时传 0 关闭 */
+    minHeight?: number | string;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,7 @@
+import type { ReactNode } from "react";
+/** 进行中时在内容上盖一层半透明遮罩与转圈；内容保持渲染 */
+export declare function LoadingOverlay({ loading, className, children, }: {
+    loading: boolean;
+    className?: string;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,93 @@
+/**
+ * 菜单基础件：命令、开关、单选组、分隔与子菜单组成的异构浮层。
+ * 键盘导航、焦点回收、外点关闭和菜单树互斥由组件内建。
+ */
+import { type ReactElement, type ReactNode } from "react";
+/** 根级：命令项触发后的整树关闭（外点/互斥由 dismiss 层逐层登记承担，D-014） */
+export interface MenuRootContextValue {
+    closeMenu: () => void;
+}
+export interface MenuItemProps {
+    icon?: ReactNode;
+    /** 快捷键提示（展示用；键监听归全局注册表，这里不接线） */
+    kbd?: string;
+    danger?: boolean;
+    disabled?: boolean;
+    onSelect?: () => void;
+    children: ReactNode;
+    className?: string;
+}
+declare function MenuItem({ icon, kbd, danger, disabled, onSelect, children, className }: MenuItemProps): import("react/jsx-runtime").JSX.Element;
+export interface MenuCheckboxItemProps {
+    checked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    icon?: ReactNode;
+    kbd?: string;
+    disabled?: boolean;
+    children: ReactNode;
+    className?: string;
+}
+declare function MenuCheckboxItem({ checked, onCheckedChange, icon, kbd, disabled, children, className, }: MenuCheckboxItemProps): import("react/jsx-runtime").JSX.Element;
+export interface MenuRadioGroupProps {
+    value?: string;
+    onValueChange?: (value: string) => void;
+    children: ReactNode;
+}
+declare function MenuRadioGroup({ value, onValueChange, children }: MenuRadioGroupProps): import("react/jsx-runtime").JSX.Element;
+export interface MenuRadioItemProps {
+    value: string;
+    icon?: ReactNode;
+    kbd?: string;
+    disabled?: boolean;
+    children: ReactNode;
+    className?: string;
+}
+declare function MenuRadioItem({ value, icon, kbd, disabled, children, className }: MenuRadioItemProps): import("react/jsx-runtime").JSX.Element;
+export interface MenuSubmenuProps {
+    label: ReactNode;
+    icon?: ReactNode;
+    disabled?: boolean;
+    children: ReactNode;
+}
+declare function MenuSubmenu({ label, icon, disabled, children }: MenuSubmenuProps): import("react/jsx-runtime").JSX.Element;
+declare function MenuSeparator(): import("react/jsx-runtime").JSX.Element;
+declare function MenuGroup({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export interface MenuProps {
+    /**
+     * 触发器（单一元素，克隆注入开合事件 / aria / ref；不强制本组件的按钮样式）。
+     * 协议同 Tooltip：元素必须透传 props 与 ref——原生元素或 {...rest} 透传的
+     * 组件；不透传的包装组件会吞掉注入，点击无反应。
+     */
+    trigger: ReactElement;
+    children: ReactNode;
+    /** 交叉轴对齐：start = 左缘 / end = 右缘对齐触发器 */
+    align?: "start" | "end";
+    /** 浮层受控（§5.3 契约；样板间常显标本用它） */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** 透传浮层（宽度控制如 w-[280px]） */
+    className?: string;
+    /** 尽量展开：主层与子层高度上限放到视口高度（默认 300px），只有视口放不下才滚动 */
+    fit?: boolean;
+}
+export declare function Menu({ trigger, children, align, open: openProp, onOpenChange, className, fit, }: MenuProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Menu {
+    var Item: typeof MenuItem;
+    var CheckboxItem: typeof MenuCheckboxItem;
+    var RadioGroup: typeof MenuRadioGroup;
+    var RadioItem: typeof MenuRadioItem;
+    var Submenu: typeof MenuSubmenu;
+    var Separator: typeof MenuSeparator;
+    var Group: typeof MenuGroup;
+}
+export interface ContextMenuProps {
+    /** 被包裹的区域（区域内在任意处右键弹出菜单） */
+    children: ReactNode;
+    /** 菜单内容（与 Menu 的 children 同构） */
+    content: ReactNode;
+    className?: string;
+}
+export declare function ContextMenu({ children, content, className }: ContextMenuProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,110 @@
+/**
+ * Notification 基础件 —— 右上角通知卡栈（mockups/notification/，承载方案 A + 卡片 V4）。
+ *
+ * 与 Toast 分工：Toast 是「你刚做了什么」的一句话回执；Notification 承载不是当下操作
+ * 引发的事件（协作者、应用更新、后台任务），有来源 / 标题 / 说明，常需作答。
+ *
+ * 卡片：34px 身份位（人 = 派生色头像，系统 = 中性图标，成败 = soft 底语义墨）+ 文字列
+ * （标题与「来源 · 相对时间」同行，说明至多 2 行）+ 横跨整卡的等宽按钮条（主按钮放最右，
+ * 次要统一描边——等分格里每格都要看得出是按钮）。不描边，ring + lift + float 三层影；
+ * 关闭钮悬停/聚焦时出现在左上外沿，不与时间抢右上角。
+ * 卡栈：新的在上，只完整显示最新 3 张，更多按底边缩放露 8px 纸边叠 2 层；关掉一张
+ * 后面的依次补位，计数标签只报数不可点，另有「全部清除」。
+ * 停留：sticky（需作答）常驻；否则 8s 自动关，悬停与作答中冻结。
+ * 作答：onClick 返回 promise 时该按钮 loading、整条锁定；兑现 → 有 resolvedText 收成
+ * 结果行 1.6s 后退场，否则直接退场；拒绝 → 说明位换成错误文案、按钮解锁。
+ * 不抢焦点（role=status + aria-live polite），不接 Esc（非阻断浮层，同 Toast）。
+ * 层级 z-[190]：Toast（200）压在通知之上，回执不被卡栈挡住。
+ *
+ * 用法：壳层挂载 <NotificationHost /> 一次；任意处 notify({...}) 返回 id，
+ * notify.update(id, patch) / notify.dismiss(id?) / notify.isActive(id)。同 id 再次
+ * notify = 原位更新（去重）。
+ * 锚定角默认右上，可传 placement="bottom-right" 纯镜像到右下；系统通知独立窗口另可
+ * 传 autoDismiss={false} 关掉自动关闭、className 覆盖容器贴边定位，并用 onItemsChange
+ * （id 列表增减）与 onCardClick（卡主体点击）把卡栈生命周期桥接到宿主窗口。
+ */
+import { type ComponentProps } from "react";
+import { type LucideIcon } from "lucide-react";
+export type NotificationTone = "neutral" | "ok" | "danger";
+export interface NotificationAction {
+    label: string;
+    /** 主动作（accent 实心）；至多一个，放在数组末尾（主按钮在最右） */
+    primary?: boolean;
+    /** 返回 promise 即进入作答中：按钮 loading、整条锁定，兑现后退场，拒绝则卡内报错 */
+    onClick?: () => unknown;
+    /** 作答成功后的结果行文案（如「已同意林然加入协作」）；不给则直接退场 */
+    resolvedText?: string;
+}
+export interface NotificationOptions {
+    /** 业务键：同 id 再次 notify 原位更新而非新增（如 "app-update"） */
+    id?: string;
+    title: string;
+    body?: string;
+    /** 来源（「协作」「应用更新」），与相对时间同排在标题右侧 */
+    source?: string;
+    /** 身份位图标；缺省按 tone 取（neutral 铃铛 / ok 对勾 / danger 警示） */
+    icon?: LucideIcon;
+    /** 人发起的通知：头像文字（通常取名字首字），优先于 icon */
+    avatar?: string;
+    /** 头像取色种子（如用户 id），同人恒同色；缺省用 avatar 本身 */
+    avatarSeed?: string;
+    /** 语义只染身份位；卡片本体一律中性 */
+    tone?: NotificationTone;
+    /** 至多 2 个 */
+    actions?: NotificationAction[];
+    /** 需作答：常驻到有答案为止（默认 false = 纯告知，duration 后自动关） */
+    sticky?: boolean;
+    duration?: number;
+    /** 事件发生时间（毫秒），缺省为 notify 调用时刻 */
+    timestamp?: number;
+}
+export interface NotificationItem extends Omit<NotificationOptions, "id" | "sticky" | "duration" | "timestamp"> {
+    id: string;
+    sticky: boolean;
+    duration: number;
+    timestamp: number;
+    /** 作答中的动作下标 */
+    busy?: number;
+    /** 作答成功后的结果行（卡片收成一行） */
+    resolvedText?: string;
+    /** 作答失败文案（替换说明位） */
+    error?: string;
+    leaving?: boolean;
+}
+export declare function notify(options: NotificationOptions): string;
+export declare namespace notify {
+    var update: (id: string, patch: Partial<Omit<NotificationOptions, "id">>) => void;
+    var dismiss: (id?: string) => void;
+    var isActive: (id: string) => boolean;
+}
+export interface NotificationCardProps extends Omit<ComponentProps<"div">, "children"> {
+    item: NotificationItem;
+    /** 相对时间的参照时刻（Host 每 30s 刷新；样板间标本可固定） */
+    now?: number;
+    onAction?: (index: number) => void;
+    onClose?: () => void;
+    /** 关闭钮常显（样板间悬停态标本用；产品里靠 hover / focus-within 出现） */
+    showClose?: boolean;
+}
+/**
+ * 单张通知卡（受 item 驱动的纯展示件）。导出供样板间构造常显标本——产品代码只应
+ * 消费 notify 命令式 API 与 NotificationHost。
+ */
+export declare function NotificationCard({ item, now, onAction, onClose, showClose, className, ...props }: NotificationCardProps): import("react/jsx-runtime").JSX.Element;
+export interface NotificationHostProps {
+    /** 卡栈锚定角，默认 "top-right" */
+    placement?: "top-right" | "bottom-right";
+    /** false 时所有卡都不自动关闭（系统通知窗口用），默认 true */
+    autoDismiss?: boolean;
+    /** 覆盖容器定位类（例如独立窗口里贴边 top-0/bottom-0 right-0），经 cn() 合并 */
+    className?: string;
+    /**
+     * store 内 id 列表变化时回报（按「已从 store 移除」口径：退场动画中的卡仍在列表里，
+     * 直到 LEAVE_MS 后真正移除才消失）；挂载时回报一次当前列表。经 id 串比较去抖，
+     * 原位更新等内容变化不会触发。
+     */
+    onItemsChange?: (ids: string[]) => void;
+    /** 非叠层卡主体被点击（卡内 button/a 上的点击不触发）；叠层卡不响应点击 */
+    onCardClick?: (id: string) => void;
+}
+export declare function NotificationHost({ placement, autoDismiss, className, onItemsChange, onCardClick, }: NotificationHostProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,28 @@
+/**
+ * 面板（白卡）族 —— 壳层内容区的基础卡片容器（A2 视觉：surface 底 + shadow-card）。
+ * pad 三档：base（宽松版式 18/20）、compact（今日页紧凑版式 12/16）、none（自管内距）。
+ * variant：raised（默认，阴影白卡，直接落在 page 底上）/ outline（细描边，落在一整张纸上——纸上再叠阴影卡会糊成一片）。
+ * PanelTitle 的下间距由调用方按域密度给（mb-1.5 / mb-2.5），避免同属性类层叠不可控。
+ */
+import type { ComponentProps } from "react";
+declare const PANEL_VARIANTS: {
+    readonly raised: "shadow-card";
+    readonly outline: "border border-line-1";
+};
+declare const PANEL_PADS: {
+    readonly base: "px-5 py-[18px]";
+    readonly compact: "px-4 py-3";
+    readonly none: "";
+};
+export declare function Panel({ className, pad, variant, ...props }: ComponentProps<"section"> & {
+    pad?: keyof typeof PANEL_PADS;
+    variant?: keyof typeof PANEL_VARIANTS;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function PanelTitle({ className, ...props }: ComponentProps<"h2">): import("react/jsx-runtime").JSX.Element;
+/** 标题行右侧的说明小字（flex 布局下与标题的间距由 gap 提供） */
+export declare function PanelNote({ className, ...props }: ComponentProps<"small">): import("react/jsx-runtime").JSX.Element;
+/** 板内空态注记（描边行，替代原 board-note 空态用法） */
+export declare function EmptyNote({ className, ...props }: ComponentProps<"p">): import("react/jsx-runtime").JSX.Element;
+/** 标题行右侧的“前往”链接（无背景，贴卡片右缘，与标题同行对齐）—— 今日页 / 发布页等共用 */
+export declare function PanelAction({ className, ...props }: ComponentProps<"button">): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,58 @@
+/**
+ * Popover 基础件 —— 锚定式可交互内容浮层（D-014）。
+ *
+ * 家族分工：Tooltip 瞬态说明（hover/focus、不可交互）、Menu 命令面板、Select 表单值
+ * 选择、Dialog 模态决策、Toast 回执；Popover 收「点击触发、内容可继续操作」的
+ * 非模态浮层——说明卡 / 过滤器组 / 色板 / 成员卡 / 卡片预览。antd 存量 Popover 的
+ * trigger="hover" 用法迁 Tooltip、placement 12 向同名直映（D-014 迁移口径）。
+ *
+ * 定位与卡片视觉组合自 AnchoredPanel（基座只有一份）；本件叠加交互层：
+ *  - click toggle（hover 说明归 Tooltip，不设 trigger props；右键归 ContextMenu）
+ *  - 外点关闭 + 嵌套链共存 + 顶层互斥（useLayerDismiss：浮层内开的 Menu/Select/
+ *    二级 Popover 不算外点）
+ *  - Esc 仅 open 态消费（焦点链 LIFO，同 Select/Menu/Dialog 口径，不进 D-003
+ *    注册表——ui 不反向依赖 page/）；Esc/Tab 关闭还焦触发器
+ *  - 打开落初始焦点：卡片内 [data-autofocus] 优先（表单放首输入框），否则卡片自身
+ *  - Tab 移出即关（非模态不圈闭）
+ *  - aria：卡片 role=dialog（非模态，无 aria-modal）+ aria-labelledby 头行；
+ *    触发器 aria-haspopup=dialog + aria-expanded
+ *  - 受控 open / onOpenChange（§5.3 浮层 open 契约；样板间常显标本用它）
+ */
+import { type ReactElement, type ReactNode } from "react";
+import type { AnchoredPlacement } from "./anchoredPosition";
+export interface PopoverProps {
+    /**
+     * 触发器（单一元素，克隆注入开合事件 / aria / ref）。协议同 Tooltip/Menu：元素
+     * 必须透传 props 与 ref——原生元素或 {...rest} 透传的组件；不透传的包装组件会
+     * 吞掉注入，点击无反应。
+     */
+    trigger?: ReactElement;
+    /** 已存在的交互元素可直接作为锚点，适用于虚拟列表单元格。 */
+    anchor?: HTMLElement | null;
+    locked?: boolean;
+    /** 内容：Popover.Header / Body / Footer 复合声明（裸内容无内边距，自查排版） */
+    children: ReactNode;
+    /** 12 向全表（引擎 flip/shift 兜底），默认 top */
+    placement?: AnchoredPlacement;
+    /** 浮层受控（§5.3 契约；样板间常显标本用它） */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** 箭头（默认开；8px 菱形，随 flip 自动换边） */
+    arrow?: boolean;
+    /** 透传浮层卡片（宽度控制如 w-[360px]，覆盖 min/max 约束） */
+    className?: string;
+}
+export declare function Popover({ trigger, anchor, locked, children, placement, open: openProp, onOpenChange, arrow, className, }: PopoverProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Popover {
+    var Header: typeof PopoverHeader;
+    var Body: ({ children, className }: import("./AnchoredPanel").AnchoredPanelBodyProps) => import("react/jsx-runtime").JSX.Element;
+    var Footer: ({ children, className }: import("./AnchoredPanel").AnchoredPanelFooterProps) => import("react/jsx-runtime").JSX.Element;
+}
+export interface PopoverHeaderProps {
+    /** 16px lucide 图标（圆底 accent-soft） */
+    icon?: ReactNode;
+    children: ReactNode;
+}
+/** 头行：随需出现——说明卡/过滤器用它，色板/成员卡可省（零框架税） */
+declare function PopoverHeader({ icon, children }: PopoverHeaderProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,7 @@
+import { ReactNode } from "react";
+interface PortalToBodyProps {
+    children: ReactNode;
+    container?: HTMLElement;
+}
+declare const PortalToBody: ({ children, container }: PortalToBodyProps) => import("react").ReactPortal;
+export default PortalToBody;

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

@@ -0,0 +1,27 @@
+/**
+ * Radio —— 单选基础件（Input 方案 A「经典描边」语言，mockups/radio/，2026-09-19 定稿）。
+ *
+ * 原生 input[type=radio] 承载语义（appearance-none 自绘皮）：组内互斥、
+ * 方向键移动即选择、读屏语义白送。形制是 Checkbox 的圆形同构：16×16 视觉圆
+ * surface + line-1，选中 = 描边转 accent + 中心 accent 实点（110ms 缩放进场）。
+ *
+ * 结构铁律（同 Checkbox）：input / 圆环 / 中心点在同一层互为兄弟——peer-*
+ * 变体只匹配 peer 的后续兄弟，深层后代会静默失效。状态语义（与 Input 裁决
+ * 同源）：
+ *  - 命中 24×24；focus-visible 才显 ring；hover 描边加深半档，聚焦时让位
+ *  - 错误态正源 aria-invalid（未选中 danger），选中压过错误（选中优先）
+ *  - 禁用：label 整项降透明 55%（fieldSet 组禁用时经 :disabled 传播同样生效）
+ *
+ * 单项不单独成组：须包在 RadioGroup 内（经 context 取 name/受控值），脱离组
+ * 使用时自传 name，checked/defaultChecked/onChange 走原生透传。
+ */
+import { type ComponentProps, type ReactNode } from "react";
+export interface RadioProps extends Omit<ComponentProps<"input">, "type"> {
+    /** 选项值（组内唯一；选中态 = RadioGroup.value 等于此值） */
+    value: string;
+    /** 主标签（点文字同选；组内忽略 checked 类受控 prop，值归组） */
+    label?: ReactNode;
+    /** 描述行（label 下方两行排布，顶对齐；说明性文案走 tau-meta 下限） */
+    description?: ReactNode;
+}
+export declare function Radio({ value, label, description, className, disabled, ...props }: RadioProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,32 @@
+/**
+ * RadioGroup —— 单选组（Input 方案 A 语言，mockups/radio/，2026-09-19 定稿）。
+ *
+ * fieldset/legend 承载组语义，原生 radio 组行为白送：Tab 一次进组（选中项/
+ * 首个可用项）、方向键移动即选择、组内互斥。组合式 children（描述行只有
+ * 组合式能表达，antd options 数据驱动不采）；排布两档 orientation，legend
+ * 随流向排（横向在行首、纵向独占一行）。
+ *
+ * 组级 disabled 走 fieldset[disabled]（浏览器原生向内传播 :disabled，
+ * Radio 的单项降透明随之生效）；name 默认 useId 生成，可显式覆盖（表单提交）。
+ */
+import { type ReactNode } from "react";
+/** 组内受控通道：Radio 消费（name/当前值/回报）；组外 Radio 退化为裸原生 radio */
+export declare const RadioGroupContext: import("react").Context<{
+    name: string;
+    value: string | null;
+    onValueChange: (value: string) => void;
+} | null>;
+export interface RadioGroupProps<Value extends string> {
+    /** 组名（legend，读屏必读；默认可见） */
+    label: ReactNode;
+    value?: Value;
+    defaultValue?: Value;
+    onValueChange?: (value: Value) => void;
+    orientation?: "horizontal" | "vertical";
+    /** radio 组提交名（默认 useId 自动生成；覆盖时须全应用内唯一） */
+    name?: string;
+    disabled?: boolean;
+    children: ReactNode;
+    className?: string;
+}
+export declare function RadioGroup<Value extends string>({ label, value: valueProp, defaultValue, onValueChange, orientation, name: nameProp, disabled, children, className, }: RadioGroupProps<Value>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,40 @@
+import React from "react";
+interface ResizeableAndHideableSidebarProps {
+    width: number;
+    open: boolean;
+    onWidthChange?: (width: number, actualWidth?: number) => void;
+    onActualWidthChange?: (actualWidth: number) => void;
+    onToggle?: () => void;
+    className?: string;
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+    minWidth?: number;
+    maxWidth?: number;
+    /**
+     * 拖拽条所在的边。
+     * 语义是“resize handle 在组件哪一侧”，不是“侧边栏停靠在哪一侧”。
+     * 例如：
+     * - 左侧侧边栏通常传 `right`
+     * - 右侧侧边栏通常传 `left`
+     */
+    resizeHandleSide?: "left" | "right";
+    /**
+     * @deprecated 兼容旧调用，等价于 `resizeHandleSide`
+     */
+    side?: "left" | "right";
+    /** 侧边栏的位置（左侧或右侧），用于确定按钮显示位置 */
+    sidebarPosition?: "left" | "right";
+    disableResize?: boolean;
+    handleOffset?: number;
+    /**
+     * 收起后是否在边缘显示统一的 hover 展开按钮。
+     * 适合“收起时完全不可见，只在边缘悬浮展开”的场景。
+     */
+    showInternalExpandButtonWhenClosed?: boolean;
+    /** 透传 WidthResizable：常驻淡分隔线标出拖拽边界 */
+    showDivider?: boolean;
+    /** 以 flex 铺满父级剩余空间，替代固定宽度（如视频笔记收起对话后材料栏独占） */
+    fillRemaining?: boolean;
+}
+declare const ResizeableAndHideableSidebar: (props: ResizeableAndHideableSidebarProps) => import("react/jsx-runtime").JSX.Element;
+export default ResizeableAndHideableSidebar;

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

@@ -0,0 +1,23 @@
+/**
+ * 侧栏拖宽热区：透明 8px 竖条，hover / 拖动时中部显出 2px accent 短线（不画分隔线）。
+ * 栏在热区的哪一侧由 side 决定——side="left" 表示栏在热区左边（向右拖变宽），
+ * "right" 表示栏在右边（向左拖变宽）。宽度夹在 [min, max]；←/→ 每次 ±16px，双击回默认宽度。
+ * 定位由调用方给（className，通常 absolute 贴在栏的内缘）。pointer capture 保证拖出窗口不丢事件。
+ */
+export interface ResizeHandleProps {
+    /** 当前宽度（受控） */
+    value: number;
+    min: number;
+    max: number;
+    onChange: (width: number) => void;
+    /** 栏在热区的哪一侧 */
+    side: "left" | "right";
+    /** 读屏用：调整的是什么（「AI 对话栏宽度」） */
+    label: string;
+    /** 双击恢复的宽度；不传则双击无操作 */
+    defaultValue?: number;
+    /** 拖动开始 / 结束（调用方可在拖动期间关掉宽度过渡，免得跟手滞后） */
+    onActiveChange?: (active: boolean) => void;
+    className?: string;
+}
+export declare function ResizeHandle({ value, min, max, onChange, side, label, defaultValue, onActiveChange, className, }: ResizeHandleProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,44 @@
+/**
+ * Segmented —— 分段单选器（Input 家族「连体描边」语言，mockups/segmented/，2026-09-23 定稿）。
+ *
+ * 02 规范 §5.2 裁决的 Tabs 官定替代：内容形态切换（字段不同构）用分段，值切换
+ * （字段同构）用 Select。容器是一枚 hairline 控件（surface + line-1，与 Input /
+ * Select 触发器同皮），段间 hairline 分割；激活段 accent-soft 轻染 + accent-text
+ * ——零轨道、零滑块、零投影（凹槽深底形态已否决，见 mockups/segmented/ 头注）。
+ *
+ * 原生 input[type=radio] 承载语义（隐藏自绘皮）：组内互斥、方向键移动即选择、
+ * Tab 一次进组白送。状态纪律同 Input 家族：hover 淡墨只落未选段（不冲淡激活染）、
+ * press 加深一档、focus-visible 才显 ring（inset 2px 不被容器圆角裁切）。
+ * 段数口径 2–5，再多该用 Select；图标段与纯图标段（label 省略，aria-label 必填）
+ * 均支持。复合组件 Segmented.Item 须包在 Segmented 内（经 context 取 name/受控值）。
+ * 外框默认 w-fit：放进 flex-col 等拉伸容器也按内容宽排，不会出现框宽段窄的空尾。
+ */
+import { type ComponentProps, type ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
+export interface SegmentedProps<Value extends string> {
+    /** 组名（aria-label，读屏必读；不渲染可见标签——分段器的上下文由摆放位置给出） */
+    label: string;
+    value?: Value;
+    defaultValue?: Value;
+    onValueChange?: (value: Value) => void;
+    size?: "sm" | "md";
+    /** 组级禁用（压过单项）；单项禁用走 Item 的 disabled */
+    disabled?: boolean;
+    /** radio 组提交名（默认 useId 自动生成；覆盖时须全应用内唯一） */
+    name?: string;
+    className?: string;
+    children: ReactNode;
+}
+export declare function SegmentedRoot<Value extends string>({ label, value: valueProp, defaultValue, onValueChange, size, disabled, name: nameProp, className, children, }: SegmentedProps<Value>): import("react/jsx-runtime").JSX.Element;
+export interface SegmentedItemProps extends Omit<ComponentProps<"input">, "type" | "value" | "name" | "checked" | "defaultChecked"> {
+    /** 段值（组内唯一；选中态 = Segmented.value 等于此值） */
+    value: string;
+    /** 段文字；省略时为纯图标段，aria-label 必填 */
+    label?: ReactNode;
+    icon?: LucideIcon;
+    disabled?: boolean;
+}
+export declare function SegmentedItem({ value, label, icon: Icon, disabled, className, ...props }: SegmentedItemProps): import("react/jsx-runtime").JSX.Element;
+export declare const Segmented: typeof SegmentedRoot & {
+    Item: typeof SegmentedItem;
+};