@q1travel/design-system 0.1.0

package/dist/design-system.d.ts

@@ -0,0 +1,1099 @@
+import { AnchorHTMLAttributes } from 'react';
+import { FocusEventHandler } from 'react';
+import { HTMLAttributes } from 'react';
+import { InputHTMLAttributes } from 'react';
+import { JSX } from 'react';
+import { KeyboardEventHandler } from 'react';
+import { MouseEventHandler } from 'react';
+import { ReactElement } from 'react';
+import { ReactNode } from 'react';
+import { RefObject } from 'react';
+import { SelectHTMLAttributes } from 'react';
+import { TextareaHTMLAttributes } from 'react';
+
+export declare function addDays(date: Date, amount: number): Date;
+
+export declare function Avatar({ title, src, letter, glyph, placeholder, icon, iconColor, size, className }: AvatarProps): JSX.Element;
+
+export declare function AvatarGroup({ members, label, size, limit, overlap, reverse, className, }: {
+    members: AvatarMember[];
+    /** 可选整组名；传入则套 role=group 作整组增强，不传则跟 Geist 默认逐个头像标注（读屏念每个成员名）。 */
+    label?: string;
+    /** 成员统一直径；缺省 32。 */
+    size?: number;
+    /** 显示上限，超出收纳为 +N；非法值（负数/NaN）忽略。 */
+    limit?: number;
+    /** 重叠像素；'auto' = 尺寸的 30% 取整（Geist 实测 16→5 / 24→7 / 32→10 / 48→14）；负数按 0 处理。 */
+    overlap?: number | 'auto';
+    /** 翻转堆叠顺序。 */
+    reverse?: boolean;
+    className?: string;
+}): JSX.Element;
+
+export declare type AvatarMember = Omit<AvatarProps, 'size' | 'className'>;
+
+export declare type AvatarProps = {
+    /** 实体本名（陈一帆、产品团队）：既是可访问名也是图片 alt。 */
+    title: string;
+    /** 头像图；加载失败自动回退到字母（failedSrc 按 src 记账，换新地址会重试）。 */
+    src?: string;
+    /** 无图回退字母（中文取姓、英文取首字母，最多两字符）；缺省时组件自动从 title 派生。 */
+    letter?: string;
+    /** 图标作头像本体（团队/组织等无人像实体）；本库自有扩展，与右下角标是两种用途。 */
+    glyph?: ReactNode;
+    /** 加载占位骨架；只用于加载态，不作长期缺省。 */
+    placeholder?: boolean;
+    /** 右下角标图标（对标 Geist With custom icon）；纯装饰，语义信息由调用方文字承载。 */
+    icon?: ReactNode;
+    /** 角标底色（任意 CSS color，建议用语义 token）；缺省中性灰盘。 */
+    iconColor?: string;
+    /** 直径像素；缺省 32（组内缺省继承组尺寸）。非法值（0/负数/NaN）按缺省处理。 */
+    size?: number;
+    className?: string;
+};
+
+declare type Axis = 'vertical' | 'horizontal' | 'free';
+
+export declare function Badge({ tone, subtle, inverted, size, icon, count, title, className, children, ...rest }: BadgeProps): JSX.Element;
+
+export declare type BadgeProps = {
+    /** 语义色调，颜色即语义：灰=中性、蓝=信息、绿=成功、琥珀=警告、红=危险。 */
+    tone?: BadgeTone;
+    /** 密集表面上的低对比形态。 */
+    subtle?: boolean;
+    /** 反转高对比形态；设置后忽略 tone/subtle。 */
+    inverted?: boolean;
+    /** 尺寸档 20/24/32（Geist 实测阶梯）。 */
+    size?: BadgeSize;
+    /** 前置图标；纯装饰（组件自动 aria-hidden），宽高随档位 12/14/16 由样式钉死。 */
+    icon?: ReactNode;
+    /** 计数徽标形态（自有扩展）：单数字圆形，多位自动撑开。 */
+    count?: boolean;
+    /** 悬停提示；纯图标（无 children）时兼作读屏可访问名——单靠 title 属性多数读屏不播报，组件会补 role=img + aria-label。 */
+    title?: string;
+} & HTMLAttributes<HTMLSpanElement>;
+
+export declare type BadgeSize = 'sm' | 'md' | 'lg';
+
+export declare type BadgeTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+
+export declare function Banner({ title, children, tone, icon, action, onDismiss, progress, className, ...rest }: BannerProps): JSX.Element;
+
+export declare type BannerProps = {
+    /** 粗体导语，一眼点题。 */
+    title: string;
+    /** 描述文案；组件统一用「 — 」与导语衔接。 */
+    children?: ReactNode;
+    /** 未设 = 页顶公告形态；设值 = 页内卡条形态（neutral 为中性卡条）。 */
+    tone?: BannerTone;
+    /** 卡条形态的前缀图标；纯装饰（组件自动 aria-hidden）。公告形态与进度形态不渲染图标。 */
+    icon?: ReactNode;
+    /** 主操作：公告形态渲染恒深药丸（无 chevron，Geist 同款）；卡条形态渲染描边药丸 + chevron。进度形态忽略 action——任务进行中不挂主跳转，完成后换普通卡条。 */
+    action?: {
+        label: string;
+        href: string;
+    };
+    /** 关闭回调；设置后渲染关闭按钮。公告形态无关闭（跟 Geist）；进度形态渲染在进度头右侧。 */
+    onDismiss?: () => void;
+    /** 进度形态（自有扩展）：value 为 0–100 的百分比（非法值归 0），label 供读屏。进度恒为卡条形态。 */
+    progress?: {
+        value: number;
+        label: string;
+    };
+} & HTMLAttributes<HTMLDivElement>;
+
+export declare type BannerTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+
+declare type BannerVariant = 'default' | 'success' | 'warning' | 'error';
+
+export declare function Book({ title, variant, color, bandColor, textColor, icon, illustration, textured, width, className, style, ...rest }: BookProps): JSX.Element;
+
+export declare type BookProps = {
+    /** 封面标题；语义由标题承载，封面其余元素均为装饰。 */
+    title: string;
+    /** stripe=顶部色带+下方标签区（Geist 默认）；simple=纯封面、标题置顶。 */
+    variant?: 'stripe' | 'simple';
+    /** 封面底色；建议传设计 token（var(--q1-color-…)），勿用裸 hex（Geist Best Practices 同款要求）。 */
+    color?: string;
+    /** stripe 色带颜色；缺省琥珀（Geist 实测默认带色）。 */
+    bandColor?: string;
+    /** 标题颜色；自定义封面色时务必保证对比可读。 */
+    textColor?: string;
+    /** 装饰图标：stripe 置于色带中央，simple 置于标题上方；组件自动 aria-hidden。 */
+    icon?: ReactNode;
+    /** 整幅插画：铺满封面、裁切；标题浮于其上；aria-hidden。 */
+    illustration?: ReactNode;
+    /** 细密交叉纹理（自有配方；Geist 的多款纹理样式记 non-goal）。仅用于主视觉，成排书架勿用。 */
+    textured?: boolean;
+    /** 数字按 px；字符串原样透传（如 clamp(...) 做响应式宽度）。内部排版随宽度等比缩放。
+     *  width 是唯一尺寸入口：用 style.width 改宽会与内部缩放脱节。 */
+    width?: number | string;
+} & Omit<HTMLAttributes<HTMLDivElement>, 'children'>;
+
+export declare function Breadcrumb({ items, label, type, }: {
+    items: BreadcrumbCrumb[];
+    label: string;
+    type?: 'text' | 'menu';
+}): JSX.Element;
+
+declare type BreadcrumbCrumb = {
+    label: string;
+    href?: string;
+    icon?: ReactNode;
+    isCurrent?: boolean;
+    isDisabled?: boolean;
+};
+
+export declare function Browser({ address, variant, tabs, children, className, ...rest }: BrowserProps): JSX.Element;
+
+export declare function BrowserAddress({ address, className }: {
+    address: string;
+    className?: string;
+}): JSX.Element;
+
+export declare function BrowserControls({ className }?: {
+    className?: string;
+}): JSX.Element;
+
+export declare function BrowserDots({ className }?: {
+    className?: string;
+}): JSX.Element;
+
+export declare function BrowserPlaceholder(): JSX.Element;
+
+export declare type BrowserProps = {
+    address: string;
+    variant?: BrowserVariant;
+    tabs?: BrowserTab[];
+    children: ReactNode;
+} & HTMLAttributes<HTMLDivElement>;
+
+export declare type BrowserTab = {
+    label: string;
+    isActive?: boolean;
+};
+
+export declare function BrowserTabs({ tabs, className }: {
+    tabs: BrowserTab[];
+    className?: string;
+}): JSX.Element;
+
+export declare type BrowserVariant = 'light' | 'dark';
+
+export declare function Button(props: ButtonProps): JSX.Element;
+
+declare type ButtonProps = {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    iconOnly?: boolean;
+    /** 圆形——仅用于 icon-only 按钮。与 rounded 互斥（同传时 circle 优先）。 */
+    circle?: boolean;
+    /** 药丸形（full radius）+ 柔和抬起阴影（对标 Geist Rounded，营销页/落地页文字 CTA 用）。与 circle 互斥。 */
+    rounded?: boolean;
+    loading?: boolean;
+    disabled?: boolean;
+    href?: string;
+    type?: 'button' | 'submit' | 'reset';
+    shortcut?: string;
+    className?: string;
+    children?: ReactNode;
+    onClick?: MouseEventHandler<HTMLButtonElement | HTMLAnchorElement>;
+    ariaLabel?: string;
+    ariaKeyshortcuts?: string;
+    /** 供 Tooltip 等外部浮层关联描述文本、绑定展开/收起时机用；不是 Button 自身的常规用法。 */
+    'aria-describedby'?: string;
+    onFocus?: FocusEventHandler<HTMLButtonElement | HTMLAnchorElement>;
+    onBlur?: FocusEventHandler<HTMLButtonElement | HTMLAnchorElement>;
+    onKeyDown?: KeyboardEventHandler<HTMLButtonElement | HTMLAnchorElement>;
+};
+
+export declare type ButtonSize = 'sm' | 'md' | 'lg';
+
+export declare type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'warning' | 'danger';
+
+export declare function CalendarGrid({ value, onChange, size, minValue, maxValue, today, }: {
+    value: RangeValue;
+    onChange: (next: RangeValue) => void;
+    size?: CalendarSize;
+    minValue?: Date;
+    maxValue?: Date;
+    today?: Date;
+}): JSX.Element;
+
+export declare type CalendarPreset = {
+    label: string;
+    getRange: () => RangeValue;
+};
+
+export declare type CalendarSize = 'large' | 'small';
+
+export declare function Card(props: CardProps): JSX.Element;
+
+declare type CardAsContainer = CardOwnProps & {
+    href?: undefined;
+} & Omit<HTMLAttributes<HTMLDivElement>, keyof CardOwnProps>;
+
+declare type CardAsLink = CardOwnProps & {
+    /** 传入则整张卡片是可导航链接，渲染为 <a>（进 Tab 序、有焦点环）。 */
+    href: string;
+} & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, keyof CardOwnProps | 'href'>;
+
+export declare type CardDirection = 'column' | 'row';
+
+declare type CardOwnProps = {
+    /** 可点击卡片的悬停附能：轻微抬起 + 边框增强 + 柔和投影，暗示可交互。仅在整卡可点时用。 */
+    hover?: boolean;
+    /** 次要表面：更弱的底色，与主卡片区分层级。 */
+    secondary?: boolean;
+    /** 分段：用分隔线把卡片切成几段（对齐 Geist borderBetween）。 */
+    divided?: boolean;
+    /** 分段方向：column 竖排（默认）/ row 横排。与 divided 正交——单传 row 只横向铺开，配 divided 才加分隔线。 */
+    direction?: CardDirection;
+    /** 常驻柔和投影（对齐 Geist shadow）：让卡片浮于背景，用于落地/营销卡片。 */
+    shadow?: boolean;
+    /** 是否带边框，默认 true。传 false 得无框卡片（靠底色/投影表达边界，对齐 Geist border 可选）。 */
+    bordered?: boolean;
+    className?: string;
+    children: ReactNode;
+};
+
+export declare type CardProps = CardAsLink | CardAsContainer;
+
+export declare function Checkbox(props: ControlOptionOwnProps & CheckboxOnlyProps & NativeInputProps): JSX.Element;
+
+declare type CheckboxOnlyProps = {
+    /** 半选：视觉态而非第三个值，由父级逻辑驱动（如"部分子项已选"）。AT 读作 mixed。 */
+    indeterminate?: boolean;
+};
+
+export declare function Choicebox({ type, label, description, extra, className, ...rest }: ChoiceboxOwnProps & NativeInputProps_2): JSX.Element;
+
+declare type ChoiceboxOwnProps = {
+    type: 'radio' | 'checkbox';
+    /** 磁贴标题（与 ControlOption 家族同名 label，不占用 HTML 原生 title）。 */
+    label: string;
+    description?: string;
+    /** 选中时展示的额外内容（如试用说明、配额明细）；未选中时隐藏。 */
+    extra?: ReactNode;
+};
+
+export declare function ClearableInput({ id, placeholder, defaultValue, disabled, kbdHint, onClear, ariaLabel, }: ClearableInputProps): JSX.Element;
+
+declare type ClearableInputProps = {
+    id: string;
+    placeholder?: string;
+    defaultValue?: string;
+    disabled?: boolean;
+    /** 空态时右侧显示 Esc/⌘K 快捷键提示，开始输入后让位给清除按钮。 */
+    kbdHint?: boolean;
+    /** 清空（点击清除按钮或按 Esc）时回调，用于联动外部状态。 */
+    onClear?: () => void;
+    /** 无可见 label 时的可访问名。有可见 label（FormField 组合）时勿再传——aria-label 会覆盖
+     *  可见标签成为可访问名，视觉与播报分叉（WCAG 2.5.3 Label in Name）。 */
+    ariaLabel?: string;
+};
+
+export declare function ClearButton({ className, label, onClick, }: {
+    className: string;
+    label: string;
+    onClick: () => void;
+}): JSX.Element;
+
+export declare function Code({ lines, ariaLabel }: {
+    lines: CodeToken[][];
+    ariaLabel?: string;
+}): JSX.Element;
+
+export declare function CodeBlock(props: CodeBlockProps): JSX.Element;
+
+declare type CodeBlockBaseProps = {
+    lineNumbers?: boolean;
+};
+
+export declare type CodeBlockLine = {
+    tokens: CodeToken[];
+    state?: 'highlight' | 'added' | 'removed';
+};
+
+declare type CodeBlockProps = CodeBlockBaseProps & ({
+    filename?: string;
+    lines: CodeBlockLine[];
+    tabs?: undefined;
+} | {
+    tabs: CodeBlockTab[];
+    filename?: undefined;
+    lines?: undefined;
+});
+
+export declare type CodeBlockTab = {
+    label: string;
+    filename?: string;
+    lines: CodeBlockLine[];
+};
+
+export declare function CodeInline({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+
+export declare type CodeToken = {
+    text: string;
+    type?: 'keyword' | 'string' | 'fn' | 'comment';
+};
+
+export declare function CodeTokens({ tokens }: {
+    tokens: CodeToken[];
+}): JSX.Element;
+
+export declare function Collapse({ title, defaultOpen, small, children, }: {
+    title: string;
+    defaultOpen?: boolean;
+    small?: boolean;
+    children: ReactNode;
+}): JSX.Element;
+
+export declare function CollapseGroup({ multiple, children }: {
+    multiple?: boolean;
+    children: ReactNode;
+}): JSX.Element;
+
+export declare function CollapsibleBreadcrumb({ items, label }: {
+    items: BreadcrumbCrumb[];
+    label: string;
+}): JSX.Element;
+
+export declare function Combobox({ options, placeholder, emptyLabel, size, disabled, error, clearable, inputId, }: ComboboxProps): JSX.Element;
+
+export declare type ComboboxOption = {
+    value: string;
+    /** 选项文本前的图标/装饰（如区域旗帜、状态点）。 */
+    prefix?: ReactNode;
+    /** 选项文本后的图标/装饰（如快捷键、外链标记）。 */
+    suffix?: ReactNode;
+};
+
+declare type ComboboxProps = {
+    options: ComboboxOption[];
+    placeholder: string;
+    /** 空状态模板的名词（「没有匹配『查询』的{emptyLabel}」）。 */
+    emptyLabel?: string;
+    size?: ComboboxSize;
+    disabled?: boolean;
+    error?: string;
+    clearable?: boolean;
+    /** 供外部 <label htmlFor> 关联；组件自身无 label 属性。 */
+    inputId?: string;
+};
+
+export declare type ComboboxSize = 'sm' | 'md' | 'lg';
+
+export declare function CommandMenu({ sections, triggerLabel, hotkey }: CommandMenuProps): JSX.Element;
+
+export declare type CommandMenuItem = {
+    label: string;
+    /** 快捷键槽（Kbd 呈现并作为标签一部分播报）。 */
+    keybind?: string;
+    /** 通用后缀（元信息文本/状态图标），装饰性 aria-hidden；语义信息应进 label。 */
+    suffix?: ReactNode;
+};
+
+declare type CommandMenuProps = {
+    sections: CommandMenuSection[];
+    triggerLabel?: string;
+    /** 绑定全局 ⌘K（macOS）/ Ctrl+K 打开。 */
+    hotkey?: boolean;
+};
+
+export declare type CommandMenuSection = {
+    /** 段标题；缺省时该段以无标题分隔线与上文分隔（对标 Geist CommandMenuDivider）。 */
+    heading?: string;
+    items: CommandMenuItem[];
+};
+
+export declare function ContextCard({ name, identity, rows, action, placement, align, children, }: ContextCardProps): JSX.Element;
+
+export declare type ContextCardAlign = 'start' | 'center' | 'end';
+
+export declare type ContextCardPlacement = 'top' | 'bottom' | 'left' | 'right';
+
+declare type ContextCardProps = {
+    name: string;
+    identity: string;
+    rows: [string, string][];
+    action?: string;
+    placement?: ContextCardPlacement;
+    align?: ContextCardAlign;
+    children: ReactNode;
+};
+
+export declare function ContextMenu({ label, entries, children, }: {
+    label: string;
+    entries: ContextMenuEntry[];
+    children: ReactNode;
+}): JSX.Element;
+
+export declare type ContextMenuEntry = {
+    type: 'item';
+    label: string;
+    icon?: ReactNode;
+    suffix?: ReactNode;
+    disabled?: boolean;
+    danger?: boolean;
+} | {
+    type: 'link';
+    label: string;
+    href: string;
+    icon?: ReactNode;
+    suffix?: ReactNode;
+} | {
+    type: 'separator';
+};
+
+export declare function ControlOption({ id, label, description, error, indeterminate, type, ...rest }: ControlOptionOwnProps & CheckboxOnlyProps & {
+    type: 'checkbox' | 'radio';
+} & NativeInputProps): JSX.Element;
+
+declare type ControlOptionOwnProps = {
+    id: string;
+    label: string;
+    description?: string;
+    error?: string;
+};
+
+export declare function CopyButton({ value, label, successMessage, size, className, }: {
+    value: string;
+    label: string;
+    successMessage?: string;
+    size?: number;
+    className?: string;
+}): JSX.Element;
+
+export declare function Description({ title, tooltip, align, ellipsis, children, }: {
+    title: string;
+    tooltip?: string;
+    align?: 'right';
+    ellipsis?: boolean;
+    children: ReactNode;
+}): JSX.Element;
+
+export declare function DestructiveActionModal({ open, onClose, title, description, confirmLabel, verificationLabel, verificationPhrase, irreversibleDescription, loading, onConfirm, }: {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    description: ReactNode;
+    confirmLabel: string;
+    verificationLabel: string;
+    verificationPhrase: string;
+    irreversibleDescription?: string;
+    /** 提交进行中：双按钮禁用、主操作显示加载指示；open 由调用方控制，加载中模态保持打开。 */
+    loading?: boolean;
+    onConfirm: () => string | null;
+}): JSX.Element | null;
+
+export declare function DotsMenu({ entries, size, disabled, align, }: {
+    entries: DotsMenuEntry[];
+    size?: 'sm' | 'md' | 'lg';
+    disabled?: boolean;
+    align?: 'start' | 'end';
+}): JSX.Element;
+
+export declare type DotsMenuEntry = {
+    label: string;
+    disabled?: boolean;
+    danger?: boolean;
+};
+
+export declare function Drawer({ open, onClose, title, children, footer, height, }: {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    children: ReactNode;
+    footer: ReactNode;
+    /** 面板最大高度（px），覆盖默认 60vh；仅当默认高度会裁切主操作时使用。 */
+    height?: number;
+}): JSX.Element | null;
+
+export declare function EmptyState({ icon, title, description, actions, live, }: {
+    icon: ReactNode;
+    title: string;
+    description: string;
+    /** CTA 区：传家族 <Button> 与次要链接；最多一个主 CTA。 */
+    actions?: ReactNode;
+    live?: boolean;
+}): JSX.Element;
+
+export declare function Entity({ leading, title, subtitle, trailing, }: {
+    leading?: ReactNode;
+    title: string;
+    subtitle?: string;
+    trailing?: ReactNode;
+}): JSX.Element;
+
+export declare function ErrorCard({ title, message, action }: {
+    title: string;
+    message?: string;
+    action?: ReactNode;
+}): JSX.Element;
+
+export declare function ErrorMessage({ label, size, action, children, }: {
+    /** 可见的粗体标签前缀（如「邮箱错误：」），点明出错对象；缺省不显示（sr-only 前缀恒在）。 */
+    label?: string;
+    size?: ErrorMessageSize;
+    /** 恢复操作插槽：可安全重试用「重试」按钮，链接式出口放 <a>。 */
+    action?: ReactNode;
+    children: ReactNode;
+}): JSX.Element;
+
+export declare type ErrorMessageSize = 'sm' | 'md' | 'lg';
+
+export declare function Feedback({ label, prompt, placeholder, inline, topics, }: {
+    label?: string;
+    prompt?: string;
+    /** textarea 占位（对标 Geist Custom Placeholder）：换成更具体的引导，帮助用户知道从哪里说起。 */
+    placeholder?: string;
+    inline?: boolean;
+    topics?: string[];
+}): JSX.Element;
+
+export declare function Fieldset({ title, subtitle, tone, footerStatus, footerAction, disabled, children, }: {
+    title?: string;
+    subtitle: string;
+    tone?: FieldsetTone;
+    footerStatus?: ReactNode;
+    footerAction?: ReactNode;
+    disabled?: boolean;
+    children?: ReactNode;
+}): JSX.Element;
+
+export declare type FieldsetTone = 'danger' | 'warning';
+
+export declare type FieldSize = 'xs' | 'sm' | 'md' | 'lg';
+
+export declare function FileTree({ nodes, label, defaultExpanded, }: {
+    nodes: FileTreeNode[];
+    label?: string;
+    defaultExpanded?: string[];
+}): JSX.Element;
+
+export declare type FileTreeNode = {
+    name: string;
+    type: 'folder' | 'file';
+    children?: FileTreeNode[];
+};
+
+export declare function FormField({ controlId, label, description, error, wide, children, }: {
+    controlId: string;
+    label: string;
+    description?: string;
+    error?: string;
+    wide?: boolean;
+    children: ReactNode;
+}): JSX.Element;
+
+export declare function Gauge({ value, size, showValue, tone, toneDirection, label, indeterminate, }: {
+    value?: number;
+    size?: GaugeSize;
+    showValue?: boolean;
+    tone?: ThresholdTone;
+    toneDirection?: GaugeToneDirection;
+    label: string;
+    indeterminate?: boolean;
+}): JSX.Element;
+
+declare type GaugeSize = 'xs' | 'sm' | 'md' | 'lg';
+
+declare type GaugeToneDirection = 'quota' | 'health';
+
+export declare function Input({ id, label, description, error, prefix, suffix, prefixStyling, suffixStyling, rounded, wide, size, className, ...rest }: {
+    id: string;
+    label: string;
+    description?: string;
+    error?: string;
+    prefix?: ReactNode;
+    suffix?: ReactNode;
+    /** 置 false 去掉前缀的灰块底色与分隔线，变成纯文本/裸图标（对标 Geist prefixStyling）。 */
+    prefixStyling?: boolean;
+    /** 置 false 去掉后缀的灰块底色与分隔线（对标 Geist suffixStyling）。 */
+    suffixStyling?: boolean;
+    /** 药丸形全圆角外框（对标 Geist rounded，实测 9999px 级 pill 半径）。 */
+    rounded?: boolean;
+    wide?: boolean;
+    size?: FieldSize;
+} & Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'size' | 'prefix'>): JSX.Element;
+
+export declare function Kbd({ meta, shift, alt, ctrl, small, children, }: {
+    meta?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    ctrl?: boolean;
+    small?: boolean;
+    children?: ReactNode;
+}): JSX.Element;
+
+export declare function Label({ htmlFor, required, children, }: {
+    htmlFor?: string;
+    required?: boolean;
+    children: string;
+}): JSX.Element;
+
+export declare function LoadingDots({ label, size }: {
+    label?: string;
+    size?: LoadingDotsSize;
+}): JSX.Element;
+
+declare type LoadingDotsSize = 'sm' | 'md' | 'lg' | number;
+
+export declare function LoadMoreButton({ loading, noGap, noBorderRadius, onClick, children, }: {
+    loading?: boolean;
+    noGap?: boolean;
+    noBorderRadius?: boolean;
+    onClick?: () => void;
+    children: ReactNode;
+}): JSX.Element;
+
+export declare function Menu({ label, entries, withChevron, align, triggerContent }: {
+    label: string;
+    entries: MenuEntry[];
+    withChevron?: boolean;
+    align?: 'start' | 'end';
+    /** 自定义触发器内容（如纯图标）；label 始终作为可访问名称的兜底，图标-only 时经 aria-label 暴露。 */
+    triggerContent?: ReactNode;
+}): JSX.Element;
+
+export declare type MenuEntry = {
+    type: 'item';
+    label: string;
+    icon?: ReactNode;
+    /** 后缀内容（如快捷键提示）；locked 项在未显式传入 suffix 时仍兜底显示锁图标。 */
+    suffix?: ReactNode;
+    disabled?: boolean;
+    locked?: boolean;
+    danger?: boolean;
+} | {
+    type: 'link';
+    label: string;
+    href: string;
+    icon?: ReactNode;
+    suffix?: ReactNode;
+} | {
+    type: 'section';
+    label: string;
+} | {
+    type: 'separator';
+};
+
+export declare function MiddleTruncate({ text, tailLength, mono }: {
+    text: string;
+    tailLength?: number;
+    mono?: boolean;
+}): JSX.Element;
+
+export declare function Modal({ open, onClose, title, children, footer, initialFocusRef, dismissable, sticky }: {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    children: ReactNode;
+    footer: ReactNode;
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    dismissable?: boolean;
+    /** 头尾固定、只有正文区域滚动；用于正文可能超出视口高度的场景（长列表、长条款）。 */
+    sticky?: boolean;
+}): JSX.Element | null;
+
+export declare function ModalInset({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+
+export declare function MultiSelect({ options, defaultSelected, placeholder, onChange }: {
+    options: string[];
+    defaultSelected?: string[];
+    placeholder: string;
+    onChange?: (next: string[]) => void;
+}): JSX.Element;
+
+declare type NativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'type'>;
+
+declare type NativeInputProps_2 = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>;
+
+export declare function Note({ type, size, filled, disabled, label, action, children, }: {
+    type?: NoteType;
+    size?: NoteSize;
+    filled?: boolean;
+    disabled?: boolean;
+    label?: string;
+    action?: string;
+    children: ReactNode;
+}): JSX.Element;
+
+declare type NoteSize = 'small' | 'default' | 'large';
+
+declare type NoteType = 'info' | 'success' | 'warning' | 'error' | 'secondary';
+
+declare type PageLink = {
+    title: string;
+};
+
+export declare function Pagination({ previous, next }: {
+    previous?: PageLink;
+    next?: PageLink;
+}): JSX.Element;
+
+export declare function PeriodCombobox({ presets, activeLabel, onPick, }: {
+    presets: CalendarPreset[];
+    activeLabel?: string;
+    onPick: (preset: CalendarPreset) => void;
+}): JSX.Element;
+
+export declare function Phone({ screenLabel }: {
+    screenLabel: string;
+}): JSX.Element;
+
+export declare function Pill({ href, size, icon, title, className, children, ...rest }: PillProps): JSX.Element;
+
+declare type PillProps = {
+    href: string;
+    size?: BadgeSize;
+    /** 前置图标；纯装饰（组件自动 aria-hidden）。 */
+    icon?: ReactNode;
+    /** 悬停提示；纯图标（无 children）时兼作读屏可访问名。 */
+    title?: string;
+} & AnchorHTMLAttributes<HTMLAnchorElement>;
+
+export declare type PopoverLayout = 'vertical' | 'horizontal';
+
+export declare function Progress({ value, max, tone, slim, stops, label, }: {
+    value: number;
+    max?: number;
+    tone?: 'neutral' | ThresholdTone;
+    slim?: boolean;
+    stops?: ProgressStop[];
+    label: string;
+}): JSX.Element;
+
+declare type ProgressStop = number | {
+    at: number;
+    label?: string;
+};
+
+export declare function ProjectBanner({ variant, message, cta }: {
+    variant?: BannerVariant;
+    message: string;
+    cta: string;
+}): JSX.Element;
+
+export declare function Radio(props: ControlOptionOwnProps & NativeInputProps): JSX.Element;
+
+export declare function RangeField({ layout, trigger, size, minValue, maxValue, pinnedTimezone, today, value, onChange, }: {
+    layout?: PopoverLayout;
+    trigger?: TriggerKind;
+    size?: CalendarSize;
+    minValue?: Date;
+    maxValue?: Date;
+    pinnedTimezone?: string;
+    /** 透传给内部 CalendarGrid（默认真实当前日期）；文档 demo 传固定值保持演示可控。 */
+    today?: Date;
+    value: RangeValue;
+    onChange: (next: RangeValue) => void;
+}): JSX.Element;
+
+export declare function RangeInputs({ value, withTime, onApply, pinnedTimezone, }: {
+    value: RangeValue;
+    withTime: boolean;
+    onApply: () => void;
+    /** 固定时区（对标 Geist pinnedTimezone）：传入时时区从可选 select 变只读文本、不可切换。 */
+    pinnedTimezone?: string;
+}): JSX.Element;
+
+export declare function RangeSlider({ min, max, step, defaultLow, defaultHigh, disabled }: {
+    min?: number;
+    max?: number;
+    step?: number;
+    defaultLow: number;
+    defaultHigh: number;
+    disabled?: boolean;
+}): JSX.Element;
+
+export declare type RangeValue = {
+    start: Date | null;
+    end: Date | null;
+};
+
+export declare function RelativeTimeCard({ relative, relativeLong, iso, local, utc, }: {
+    relative: string;
+    relativeLong: string;
+    iso: string;
+    local: string;
+    utc: string;
+}): JSX.Element;
+
+export declare function Scroller({ axis, label, children, }: {
+    axis: Axis;
+    label: string;
+    children: ReactNode;
+}): JSX.Element;
+
+export declare function ScrollerWithButtons({ axis, contentName, label, children, }: {
+    axis?: 'horizontal' | 'vertical';
+    contentName: string;
+    label: string;
+    children: ReactNode;
+}): JSX.Element;
+
+export declare function SearchInput({ id, ariaLabel, placeholder, defaultValue, disabled, loading, kbdHint, icon, }: {
+    id: string;
+    ariaLabel: string;
+    placeholder: string;
+    defaultValue?: string;
+    disabled?: boolean;
+    loading?: boolean;
+    kbdHint?: boolean;
+    icon?: ReactNode;
+}): JSX.Element;
+
+export declare function Select({ id, label, description, error, wide, size, prefix, suffix, className, children, ...rest }: {
+    id: string;
+    label: string;
+    description?: string;
+    error?: string;
+    wide?: boolean;
+    size?: FieldSize;
+    prefix?: ReactNode;
+    /** 装饰性后缀图标（aria-hidden），渲染在下拉箭头左侧；跟 prefix 前缀一样不承载信息，可访问名称仍完全来自 label。 */
+    suffix?: ReactNode;
+    children: ReactNode;
+} & Omit<SelectHTMLAttributes<HTMLSelectElement>, 'id' | 'children' | 'size' | 'prefix'>): JSX.Element;
+
+export declare function Separator({ orientation, decorative, className, }: {
+    orientation?: SeparatorOrientation;
+    decorative?: boolean;
+    className?: string;
+}): JSX.Element;
+
+export declare type SeparatorOrientation = 'horizontal' | 'vertical';
+
+export declare function Sheet({ open, onClose, title, side, children, footer }: {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    side?: SheetSide;
+    children: ReactNode;
+    footer?: ReactNode;
+}): JSX.Element | null;
+
+export declare type SheetSide = 'top' | 'right' | 'bottom' | 'left';
+
+export declare function ShowMore({ items, initial, noBorder, initialExpanded, }: {
+    items: string[];
+    initial?: number;
+    noBorder?: boolean;
+    /** 仅用于演示常驻展开态的初始值；组件仍是非受控的，不支持中途从外部切换展开状态。 */
+    initialExpanded?: boolean;
+}): JSX.Element;
+
+export declare function Skeleton({ shape, animated, show, className, children, }: {
+    shape?: SkeletonShape;
+    animated?: boolean;
+    /** 包裹模式：数据就绪后置 true，原地显示子内容。 */
+    show?: boolean;
+    className?: string;
+    children?: ReactNode;
+}): JSX.Element;
+
+export declare type SkeletonShape = 'rounded' | 'pill' | 'squared';
+
+export declare function Slider({ label, unit, min, max, step, defaultValue }: {
+    label: string;
+    unit: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    defaultValue: number;
+}): JSX.Element;
+
+export declare function Snippet({ text, prompt, inverted, tone, copyText, onCopy, }: {
+    text: string | string[];
+    prompt?: boolean;
+    inverted?: boolean;
+    tone?: SnippetTone;
+    /** 显示与复制内容分离（对标 Geist）：传了就复制它，不传复制显示内容。 */
+    copyText?: string;
+    /** 复制触发后调用，供外部消费复制事件（如埋点）；不代表剪贴板写入一定成功。 */
+    onCopy?: () => void;
+}): JSX.Element;
+
+declare type SnippetTone = 'info' | 'danger' | 'warning';
+
+export declare function Spinner({ size, tone, label, }: {
+    size?: SpinnerSize;
+    tone?: SpinnerTone;
+    label?: string;
+}): JSX.Element;
+
+export declare type SpinnerSize = 'sm' | 'md' | 'lg' | 'xl';
+
+export declare type SpinnerTone = 'default' | 'danger' | 'success' | 'info';
+
+export declare function SplitButton({ label, entries, variant, size, align, menuButtonLabel, icon }: {
+    label: string;
+    entries: SplitButtonEntry[];
+    variant?: 'default' | 'secondary';
+    size?: 'sm' | 'md' | 'lg';
+    align?: 'start' | 'end';
+    menuButtonLabel: string;
+    icon?: ReactNode;
+}): JSX.Element;
+
+export declare type SplitButtonEntry = {
+    label: string;
+    danger?: boolean;
+    icon?: ReactNode;
+};
+
+export declare function StatusDot({ tone, label, animated, showLabel, titlePrefix, }: {
+    tone: StatusDotTone;
+    label: string;
+    animated?: boolean;
+    showLabel?: boolean;
+    titlePrefix?: string;
+}): JSX.Element;
+
+export declare type StatusDotTone = 'neutral' | 'warning' | 'success' | 'danger';
+
+export declare function Switch({ options, ariaLabel, name, defaultValue, onChange, size, fullWidth, iconOnly, }: {
+    options: SwitchOption[];
+    ariaLabel: string;
+    name?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    size?: 'sm' | 'md' | 'lg';
+    fullWidth?: boolean;
+    /** 纯图标模式：文字标签仍在，只是视觉隐藏（sr-only），可访问名称不丢失。 */
+    iconOnly?: boolean;
+}): JSX.Element | null;
+
+export declare type SwitchOption = {
+    value: string;
+    label: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+    /** 补充说明（原生 title，桌面端悬浮显示）；用于图标模式下文字看不出来的额外上下文。 */
+    tooltip?: string;
+};
+
+export declare type TabItem = {
+    id: string;
+    label: string;
+    content: ReactNode;
+    icon?: ReactNode;
+    disabled?: boolean;
+    /** 禁用原因（原生 title，桌面端悬浮显示）；放在外层包装上，因为禁用按钮本身在部分浏览器不触发 hover。 */
+    tooltip?: string;
+};
+
+export declare function Tabs({ tabs, ariaLabel, variant, }: {
+    tabs: TabItem[];
+    ariaLabel: string;
+    variant?: 'default' | 'secondary';
+}): JSX.Element | null;
+
+export declare function Textarea({ id, label, description, error, wide, size, className, ...rest }: {
+    id: string;
+    label: string;
+    description?: string;
+    error?: string;
+    wide?: boolean;
+    size?: FieldSize;
+} & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'id'>): JSX.Element;
+
+export declare function TextWithCopyButton({ text, copyValue, successMessage, size, }: {
+    text: string;
+    copyValue?: string;
+    successMessage?: string;
+    size?: 'default' | 'small';
+}): JSX.Element;
+
+export declare function ThemeSwitcher({ small, disabled }: {
+    small?: boolean;
+    disabled?: boolean;
+}): JSX.Element;
+
+declare type ThresholdTone = 'primary' | 'success' | 'warning' | 'danger';
+
+declare type ToastContextValue = {
+    push: (toast: ToastOptions) => void;
+    dismiss: (id: number) => void;
+};
+
+export declare type ToastOptions = {
+    tone?: ToastTone;
+    /** 支持纯文本或富文本（如加粗/行内链接）；aria-live 区域会播报文本内容，行内链接仍可被 Tab 到并激活。 */
+    title: ReactNode;
+    description?: ReactNode;
+    actionLabel?: string;
+    preserve?: boolean;
+    duration?: number;
+};
+
+export declare function ToastProvider({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+
+export declare type ToastTone = 'default' | 'success' | 'warning' | 'error';
+
+export declare function Toggle({ defaultOn, disabled, size, onColor, label, description, labelSide, ariaLabel, }: {
+    defaultOn?: boolean;
+    disabled?: boolean;
+    size?: ToggleSize;
+    onColor?: string;
+    label?: string;
+    description?: string;
+    labelSide?: 'left' | 'right';
+    ariaLabel?: string;
+}): JSX.Element;
+
+export declare type ToggleSize = 'sm' | 'md' | 'lg';
+
+export declare function Tooltip({ content, placement, delay, triggerLabel, children, align, tip, center, }: {
+    content: ReactNode;
+    placement?: TooltipPlacement;
+    delay?: number;
+    /** 内部默认触发器的文案；传 children 时不使用。 */
+    triggerLabel?: string;
+    /** 自定义触发器：包裹任意单个元素/组件（Button、原生 a/span 等）代替内部默认按钮。 */
+    children?: ReactElement<TooltipTriggerProps>;
+    /** 提示体相对触发器的对齐方式：垂直方位（top/bottom）沿水平轴对齐，水平方位（left/right）沿垂直轴对齐。 */
+    align?: TooltipAlign;
+    /** 是否显示指向触发器的箭头指示器。 */
+    tip?: boolean;
+    /** 提示文本是否居中对齐（默认左对齐）。 */
+    center?: boolean;
+}): JSX.Element;
+
+declare type TooltipAlign = 'start' | 'center' | 'end';
+
+export declare type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+
+declare type TooltipTriggerProps = {
+    'aria-describedby'?: string;
+    onFocus?: (event: never) => void;
+    onBlur?: (event: never) => void;
+    onKeyDown?: (event: {
+        key: string;
+    }) => void;
+};
+
+export declare type TriggerKind = 'default' | 'compact';
+
+export declare function useCopy(): {
+    copied: boolean;
+    copy: (value: string, successMessage?: string) => Promise<void>;
+    reset: () => void;
+};
+
+export declare function useToast(): ToastContextValue;
+
+export declare function Video({ controls, loop }: {
+    controls?: boolean;
+    loop?: boolean;
+}): JSX.Element;
+
+export { }