@q1travel/design-system 0.16.0 → 0.17.0

package/dist-pkg/design-system.d.ts

@@ -3,14 +3,17 @@ import { ButtonHTMLAttributes } from 'react';
 import { ComponentPropsWithoutRef } from 'react';
 import { CSSProperties } from 'react';
 import { FocusEventHandler } from 'react';
+import { ForwardRefExoticComponent } from 'react';
 import { HTMLAttributes } from 'react';
 import { InputHTMLAttributes } from 'react';
 import { JSX } from 'react';
 import { KeyboardEventHandler } from 'react';
 import { MouseEventHandler } from 'react';
+import { PointerEventHandler } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { Ref } from 'react';
+import { RefAttributes } from 'react';
 import { RefObject } from 'react';
 import { SelectHTMLAttributes } from 'react';
 import { TableHTMLAttributes } from 'react';
@@ -123,10 +126,10 @@ export declare type BannerTone = 'neutral' | 'info' | 'success' | 'warning' | 'd
 
 export 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 function Book({ title, variant, color, bandColor, textColor, icon, illustration, textured, width, className, style, onLostPointerCapture, onPointerCancel, onPointerDown, onPointerLeave, onPointerUp, ...rest }: BookProps): JSX.Element;
 
 export declare type BookProps = {
-    /** 封面标题；语义由标题承载，封面其余元素均为装饰。 */
+    /** 封面标题；完整文本保留在 DOM，视觉最多四行；封面其余元素均为装饰。 */
     title: string;
     /** stripe=顶部色带+下方标签区（默认）；simple=纯封面、标题置顶。 */
     variant?: 'stripe' | 'simple';
@@ -136,9 +139,9 @@ export declare type BookProps = {
     bandColor?: string;
     /** 标题颜色；自定义封面色时务必保证对比可读。 */
     textColor?: string;
-    /** 装饰图标：stripe 置于色带中央，simple 置于标题上方；组件自动 aria-hidden。 */
+    /** 装饰图标：stripe 置于色带中央，simple 置于标题上方；组件自动 aria-hidden + inert。 */
     icon?: ReactNode;
-    /** 整幅插画：铺满封面、裁切；标题浮于其上；aria-hidden。 */
+    /** 整幅插画：铺满封面、裁切；标题浮于其上；aria-hidden + inert。 */
     illustration?: ReactNode;
     /** 细密交叉纹理（自有配方）；只提供单一纹理样式，未做多纹理体系（记 non-goal）。仅用于主视觉，成排书架勿用。 */
     textured?: boolean;
@@ -199,15 +202,67 @@ export declare type BrowserVariant = 'light' | 'dark';
 
 export declare function Button(props: ButtonProps): JSX.Element;
 
-declare type ButtonBaseProps = {
-    variant?: ButtonVariant;
-    size?: ButtonSize;
-    svgOnly?: boolean;
+declare type ButtonAccessibleName = {
+    'aria-label': string;
+    /**
+     * @deprecated Deprecated in the unreleased post-0.4.0 migration on 2026-07-20.
+     * Use aria-label. Migration is tracked by #59; removal conditions are in contracts/button-api-compatibility.md.
+     */
+    ariaLabel?: string;
+} | {
+    'aria-label'?: never;
     /**
      * @deprecated Deprecated in the unreleased post-0.4.0 migration on 2026-07-20.
-     * Use svgOnly. Migration is tracked by #59; removal conditions are in contracts/button-api-compatibility.md.
+     * Use aria-label. Migration is tracked by #59; removal conditions are in contracts/button-api-compatibility.md.
      */
+    ariaLabel: string;
+};
+
+declare type ButtonBaseProps = ButtonSharedProps & ButtonIconLayout;
+
+declare type ButtonIconLayout = ({
+    svgOnly: true;
+    /** @deprecated Use svgOnly. Removal conditions are in contracts/button-api-compatibility.md. */
     iconOnly?: boolean;
+} & ButtonAccessibleName) | ({
+    svgOnly?: undefined;
+    /** @deprecated Use svgOnly. Removal conditions are in contracts/button-api-compatibility.md. */
+    iconOnly?: boolean;
+} & ButtonAccessibleName) | ({
+    svgOnly: false;
+    /** @deprecated Use svgOnly. Removal conditions are in contracts/button-api-compatibility.md. */
+    iconOnly?: boolean;
+} & OptionalButtonAccessibleName) | ({
+    svgOnly?: undefined;
+    /** @deprecated Use svgOnly. Removal conditions are in contracts/button-api-compatibility.md. */
+    iconOnly?: false | undefined;
+} & OptionalButtonAccessibleName);
+
+export declare function ButtonLink(props: ButtonLinkProps): JSX.Element;
+
+declare type ButtonLinkBaseProps = DistributiveOmit<ButtonBaseProps, 'type'>;
+
+export declare type ButtonLinkProps = ButtonLinkBaseProps & Omit<ComponentPropsWithoutRef<'a'>, keyof ButtonLinkBaseProps | 'href'> & {
+    /**
+     * @deprecated Deprecated in the unreleased post-0.4.0 migration on 2026-07-20.
+     * ButtonLink renders an anchor and ignores this compatibility field.
+     * Migration is tracked by #59; removal conditions are in contracts/button-api-compatibility.md.
+     */
+    type?: ButtonBaseProps['type'];
+    href: string;
+    [dataAttribute: `data-${string}`]: string | number | boolean | null | undefined;
+    ref?: Ref<HTMLAnchorElement>;
+};
+
+export declare type ButtonProps = ButtonBaseProps & Omit<ComponentPropsWithoutRef<'button'>, keyof ButtonBaseProps> & {
+    [dataAttribute: `data-${string}`]: string | number | boolean | null | undefined;
+    /** 供 focus 管理、测量、浮层定位等场景使用。 */
+    ref?: Ref<HTMLButtonElement>;
+};
+
+declare type ButtonSharedProps = {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
     /** 圆形——仅用于 icon-only 按钮。与 rounded 互斥（同传时 circle 优先）。 */
     circle?: boolean;
     /** 药丸形（full radius）+ 柔和抬起阴影，营销页/落地页文字 CTA 用。与 circle 互斥。 */
@@ -237,41 +292,11 @@ declare type ButtonBaseProps = {
     prefix?: ReactNode;
     /** 文字后置图标槽，同上。 */
     suffix?: ReactNode;
-    'aria-label'?: string;
-    /**
-     * @deprecated Deprecated in the unreleased post-0.4.0 migration on 2026-07-20.
-     * Use aria-label. Migration is tracked by #59; removal conditions are in contracts/button-api-compatibility.md.
-     */
-    ariaLabel?: string;
     ariaKeyshortcuts?: string;
     /** 供 Tooltip 等外部浮层关联描述文本、绑定展开/收起时机用；不是 Button 自身的常规用法。 */
     'aria-describedby'?: string;
 };
 
-export declare function ButtonLink(props: ButtonLinkProps): JSX.Element;
-
-export declare type ButtonLinkProps = Omit<ButtonBaseProps, 'type'> & {
-    /**
-     * @deprecated Deprecated in the unreleased post-0.4.0 migration on 2026-07-20.
-     * ButtonLink renders an anchor and ignores this compatibility field.
-     * Migration is tracked by #59; removal conditions are in contracts/button-api-compatibility.md.
-     */
-    type?: ButtonBaseProps['type'];
-    href: string;
-    onClick?: MouseEventHandler<HTMLAnchorElement>;
-    onFocus?: FocusEventHandler<HTMLAnchorElement>;
-    onBlur?: FocusEventHandler<HTMLAnchorElement>;
-    onKeyDown?: KeyboardEventHandler<HTMLAnchorElement>;
-    'aria-keyshortcuts'?: string;
-    ref?: Ref<HTMLAnchorElement>;
-};
-
-export declare type ButtonProps = ButtonBaseProps & Omit<ComponentPropsWithoutRef<'button'>, keyof ButtonBaseProps> & {
-    [dataAttribute: `data-${string}`]: string | number | boolean | null | undefined;
-    /** 供 focus 管理、测量、浮层定位等场景使用。 */
-    ref?: Ref<HTMLButtonElement>;
-};
-
 export declare type ButtonSize = 'sm' | 'md' | 'lg';
 
 export declare type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'warning' | 'danger';
@@ -359,7 +384,7 @@ declare type CheckboxOnlyProps = {
 /** Checkbox 的完整 props。消费方包一层时用它标注，无需知道内部由哪几块组合而成。 */
 export declare type CheckboxProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & ControlOptionNativeInputProps;
 
-export declare function Choicebox({ type, label, description, extra, className, ...rest }: ChoiceboxProps): JSX.Element;
+export declare function Choicebox({ type, label, description, extra, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, ...rest }: ChoiceboxProps): JSX.Element;
 
 declare type ChoiceboxNativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>;
 
@@ -375,27 +400,30 @@ declare type ChoiceboxOwnProps = {
 /** Choicebox 的完整 props。 */
 export declare type ChoiceboxProps = ChoiceboxOwnProps & ChoiceboxNativeInputProps;
 
-export declare function ClearableInput({ id, placeholder, defaultValue, disabled, kbdHint, onClear, ariaLabel, }: ClearableInputProps): JSX.Element;
+export declare function ClearableInput({ id, placeholder, value: controlledValue, defaultValue, onValueChange, disabled, readOnly, kbdHint, onClear, ariaLabel, ref, className, onChange: onInputChange, onKeyDown: onInputKeyDown, ...inputProps }: ClearableInputProps): JSX.Element;
 
 export declare type ClearableInputProps = {
     id: string;
-    placeholder?: string;
+    value?: string;
     defaultValue?: string;
-    disabled?: boolean;
-    /** 空态时右侧显示 Esc/⌘K 快捷键提示，开始输入后让位给清除按钮。 */
+    /** 键入、点击清除和按 Esc 清除共用的值变化通道。 */
+    onValueChange?: (value: string) => void;
+    /** 有可清除内容时显示组件已真实接线的 Esc 提示。 */
     kbdHint?: boolean;
     /** 清空（点击清除按钮或按 Esc）时回调，用于联动外部状态。 */
     onClear?: () => void;
     /** 无可见 label 时的可访问名。有可见 label（FormField 组合）时勿再传——aria-label 会覆盖
      * 可见标签成为可访问名，视觉与播报分叉（WCAG 2.5.3 Label in Name）。 */
     ariaLabel?: string;
-};
+    /** React 19 ref-as-prop，指向原生 text input。 */
+    ref?: Ref<HTMLInputElement>;
+} & Omit<InputHTMLAttributes<HTMLInputElement>, 'aria-label' | 'defaultValue' | 'id' | 'ref' | 'type' | 'value'>;
 
-export declare function ClearButton({ className, label, onClick, }: {
+export declare function ClearButton({ className, label, onClick, ...buttonProps }: {
     className: string;
     label: string;
     onClick: () => void;
-}): JSX.Element;
+} & Omit<ComponentPropsWithoutRef<'button'>, 'aria-label' | 'className' | 'onClick' | 'type'>): JSX.Element;
 
 export declare function Code({ lines, ariaLabel }: {
     lines: CodeToken[][];
@@ -442,11 +470,13 @@ export declare function CodeTokens({ tokens }: {
     tokens: CodeToken[];
 }): JSX.Element;
 
-export declare function Collapse({ title, defaultOpen, small, children, }: {
+export declare function Collapse({ title, defaultOpen, small, headingLevel, children, }: {
     /** 固定文案传字符串；随展开/收起切换文案（如"显示代码"/"收起代码"）传函数，入参为当前 open 状态。 */
     title: string | ((open: boolean) => string);
     defaultOpen?: boolean;
     small?: boolean;
+    /** 标题层级：默认 h3；按宿主页面的标题树传 1-6。 */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
     children: ReactNode;
 }): JSX.Element;
 
@@ -528,6 +558,8 @@ export declare type CommandMenuItem = {
     keybind?: string;
     /** 通用后缀（元信息文本/状态图标），装饰性 aria-hidden；语义信息应进 label。 */
     suffix?: ReactNode;
+    /** 面板先关闭并归还焦点，再同步执行命令；导航、新弹层与异步状态由调用方负责。 */
+    onSelect?: () => void;
 };
 
 export declare type CommandMenuProps = {
@@ -543,22 +575,47 @@ export declare type CommandMenuSection = {
     items: CommandMenuItem[];
 };
 
-export declare function ContextCard({ name, identity, rows, action, placement, align, children, }: ContextCardProps): JSX.Element;
+export declare function ContextCard({ name, identity, rows, action, onAction, actionHref, placement, align, children, }: ContextCardProps): JSX.Element;
+
+declare type ContextCardAction = {
+    action?: string;
+    onAction?: never;
+    actionHref?: never;
+} | {
+    action: string;
+    onAction: MouseEventHandler<HTMLButtonElement>;
+    actionHref?: never;
+} | {
+    action: string;
+    actionHref: string;
+    onAction?: never;
+};
 
 export declare type ContextCardAlign = 'start' | 'center' | 'end';
 
 export declare type ContextCardPlacement = 'top' | 'bottom' | 'left' | 'right';
 
-export declare type ContextCardProps = {
+export declare type ContextCardProps = ContextCardAction & {
     name: string;
     identity: string;
     rows: [string, string][];
-    action?: string;
     placement?: ContextCardPlacement;
     align?: ContextCardAlign;
+    /** 自定义组件应接受 ContextCardTriggerProps，并把注入的 class、ARIA 与事件转发到真实交互元素。 */
     children: ReactNode;
 };
 
+export declare type ContextCardTriggerProps = {
+    className?: string;
+    'aria-expanded'?: boolean;
+    'aria-controls'?: string;
+    onFocus?: FocusEventHandler<HTMLElement>;
+    onBlur?: FocusEventHandler<HTMLElement>;
+    onPointerDown?: PointerEventHandler<HTMLElement>;
+    onClick?: MouseEventHandler<HTMLElement>;
+    onKeyDown?: KeyboardEventHandler<HTMLElement>;
+};
+
 export declare function ContextMenu({ label, entries, children, }: {
     label: string;
     entries: ContextMenuEntry[];
@@ -572,6 +629,7 @@ export declare type ContextMenuEntry = {
     suffix?: ReactNode;
     disabled?: boolean;
     danger?: boolean;
+    onSelect?: () => void;
 } | {
     type: 'link';
     label: string;
@@ -660,7 +718,7 @@ export declare type ContextSwitcherSearch = {
     noResults: ContextSwitcherEmptyState;
 };
 
-export declare function ControlOption({ id, label, description, error, indeterminate, ref, type, ...rest }: ControlOptionProps): JSX.Element;
+export declare function ControlOption({ id, label, description, error, indeterminate, ref, type, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, onClick, ...rest }: ControlOptionProps): JSX.Element;
 
 declare type ControlOptionNativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'type'>;
 
@@ -703,9 +761,11 @@ export declare function DestructiveActionModal({ open, onClose, title, descripti
     irreversibleDescription?: string;
     /** 提交进行中：双按钮禁用、主操作显示加载指示；open 由调用方控制，加载中模态保持打开。 */
     loading?: boolean;
-    onConfirm: () => string | null;
+    onConfirm: () => string | null | Promise<string | null>;
 }): ReactNode;
 
+declare type DistributiveOmit<Props, Keys extends PropertyKey> = Props extends unknown ? Omit<Props, Keys> : never;
+
 export declare type DocsPageLink = {
     title: string;
     href: string;
@@ -729,6 +789,8 @@ export declare type DotsMenuEntry = {
     label: string;
     disabled?: boolean;
     danger?: boolean;
+    /** 菜单先关闭并归还焦点，再同步执行动作；确认、撤销与异步状态由调用方负责。 */
+    onSelect?: () => void;
 };
 
 export declare function Drawer({ open, onClose, title, children, footer, height, }: {
@@ -764,14 +826,16 @@ export declare function ErrorCard({ title, message, action }: {
     action?: ReactNode;
 }): JSX.Element;
 
-export declare function ErrorMessage({ label, size, action, children, }: {
+export declare function ErrorMessage({ label, size, action, children, className, 'aria-live': ariaLive, 'aria-atomic': ariaAtomic, ...nativeProps }: ErrorMessageProps): JSX.Element;
+
+export declare type ErrorMessageProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'> & {
     /** 可见的粗体标签前缀（如「邮箱错误：」），点明出错对象；缺省不显示（q1-sr-only 前缀恒在）。 */
     label?: string;
     size?: ErrorMessageSize;
-    /** 恢复操作插槽：可安全重试用「重试」按钮，链接式出口放 <a>。 */
+    /** 恢复操作插槽；字段可重新验证时传 Button，链接式出口传原生链接或 Link。 */
     action?: ReactNode;
     children: ReactNode;
-}): JSX.Element;
+};
 
 export declare type ErrorMessageSize = 'sm' | 'md' | 'lg';
 
@@ -783,14 +847,26 @@ export declare type ExternalOverlayRegistration = {
     getContainer: () => HTMLElement | null;
 };
 
-export declare function Feedback({ label, prompt, placeholder, inline, topics, }: {
+export declare function Feedback({ label, prompt, placeholder, inline, topics, onSubmit, disabled, }: FeedbackProps): JSX.Element;
+
+export declare interface FeedbackProps {
     label?: string;
     prompt?: string;
     /** textarea 占位：换成更具体的引导，帮助用户知道从哪里说起。 */
     placeholder?: string;
     inline?: boolean;
     topics?: string[];
-}): JSX.Element;
+    onSubmit?: (payload: FeedbackSubmitPayload) => void | Promise<void>;
+    disabled?: boolean;
+}
+
+export declare type FeedbackRating = 1 | 2 | 3 | 4;
+
+export declare interface FeedbackSubmitPayload {
+    rating: FeedbackRating | null;
+    topic: string;
+    comment: string;
+}
 
 declare type FieldBareProps = {
     label?: never;
@@ -798,7 +874,7 @@ declare type FieldBareProps = {
     error?: never;
 };
 
-export declare function Fieldset({ title, subtitle, tone, footerStatus, footerAction, disabled, children, }: {
+export declare function Fieldset({ title, subtitle, tone, footerStatus, footerAction, disabled, children, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, }: {
     title?: string;
     subtitle: string;
     tone?: FieldsetTone;
@@ -806,6 +882,10 @@ export declare function Fieldset({ title, subtitle, tone, footerStatus, footerAc
     footerAction?: ReactNode;
     disabled?: boolean;
     children?: ReactNode;
+    /** 无可见 title 时，为字段组提供可访问名称。 */
+    'aria-label'?: string;
+    /** 用外部可见文本命名字段组；与原生 fieldset 属性一致。 */
+    'aria-labelledby'?: string;
 }): JSX.Element;
 
 export declare type FieldsetTone = 'danger' | 'warning';
@@ -856,7 +936,7 @@ export declare type GaugeToneDirection = 'quota' | 'health';
 /** One coordinator per document, shared with all package overlays. Null during SSR. */
 export declare function getOverlayCoordinator(doc?: Document | null): OverlayCoordinator | null;
 
-export declare function IconButton({ 'aria-label': canonicalAriaLabel, ariaLabel: legacyAriaLabel, ...rest }: IconButtonProps): JSX.Element;
+export declare function IconButton({ 'aria-label': canonicalAriaLabel, ariaLabel: legacyAriaLabel, 'aria-pressed': ariaPressed, disabled, loading, onClick, onBlur, onKeyDown, onPointerCancel, onPointerDown, onPointerLeave, onPointerUp, onLostPointerCapture, ...rest }: IconButtonProps): JSX.Element;
 
 declare type IconButtonAccessibleName = {
     'aria-label': string;
@@ -891,7 +971,7 @@ export declare type IconButtonProps = IconButtonAccessibleName & IconButtonBaseP
     ref?: Ref<HTMLButtonElement>;
 };
 
-export declare function Input({ id, label, description, error, invalid, errorId, ref, prefix, suffix, prefixStyling, suffixStyling, rounded, wide, size, className, revealable, revealed, onRevealedChange, revealLabel, hideLabel, ...rest }: {
+export declare function Input({ id, label, description, error, invalid, errorId, ref, prefix, suffix, prefixStyling, suffixStyling, rounded, wide, size, className, revealable, revealed, onRevealedChange, revealLabel, hideLabel, disabled, ...rest }: {
     /** 可选：未传时内部 useId 兜底（对齐 Combobox）；显式传入时行为同 0.3.0。 */
     id?: string;
     /** 置 aria-invalid 的业务校验态，不渲染文案；与壳模式 error 并轨（invalid || Boolean(error)）。 */
@@ -933,13 +1013,13 @@ export declare function Input({ id, label, description, error, invalid, errorId,
 export declare function JsonView({ value, singleLine, wrap, collapsedDepth, highlight, embedded, label, className, }: JsonViewProps): JSX.Element;
 
 export declare type JsonViewProps = {
-    /** 要展示的值。函数与 symbol 不属于 JSON，会渲染为不可序列化标记。 */
+    /** 要展示的值。函数、symbol 与 undefined 不属于 JSON，会渲染为不可序列化标记。 */
     value: unknown;
-    /** 单行紧凑呈现：折叠全部层级、不换行，用于表格单元格或日志行。 */
+    /** 单行紧凑呈现：压平全部层级、不换行，用于表格单元格或日志行。 */
     singleLine?: boolean;
-    /** 长字符串在容器内换行，而不是横向滚动。 */
+    /** 长字符串在容器内换行，而不是横向滚动；singleLine 为 true 时单行优先。 */
     wrap?: boolean;
-    /** 初始折叠深度：0 表示只展开根，1 表示展开一层；缺省全部展开。 */
+    /** 初始折叠深度：0 表示全部折叠，1 表示只展开根；缺省全部展开。 */
     collapsedDepth?: number;
     /** 需要强调的键。`a.b` 形式按完整路径精确匹配；裸键名（如 `status`）在任意深度命中，
      * 用于「把所有 status 字段都标出来」这类排查。两种写法可混用。 */
@@ -981,16 +1061,16 @@ export declare function Label({ htmlFor, required, children, }: {
 export declare function Link({ href, tone, external, className, children, ref, ...rest }: LinkProps): JSX.Element;
 
 export declare type LinkProps = {
-    /** 目标地址。省略时渲染为不可点的当前项文本（例：面包屑末节、已停用的外链）。 */
+    /** 目标地址。省略时渲染为静态文本，不表示 disabled 链接。 */
     href?: string;
     tone?: LinkTone;
     /**
      * 站外链接：追加一枚外链图标，并补 rel="noopener noreferrer"。
      *
-     * 图标不是装饰——它是「点下去会离开当前上下文」的预告。省掉它，用户要到新标签页
-     * 打开之后才知道自己被带走了。
+     * 图标提示目的地位于站外；是否新开标签页仍由 target 决定。
      */
     external?: boolean;
+    /** 仅在 href 存在、渲染为原生锚点时绑定。 */
     ref?: Ref<HTMLAnchorElement>;
     children?: ReactNode;
 } & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>;
@@ -1004,13 +1084,18 @@ export declare function LoadingDots({ label, size }: {
 
 export declare type LoadingDotsSize = 'sm' | 'md' | 'lg' | number;
 
-export declare function LoadMoreButton({ loading, noGap, noBorderRadius, onClick, children, }: {
+export declare function LoadMoreButton({ loading, loadingLabel, noGap, noBorderRadius, disabled, type, className, children, onClick, onKeyDown, ref, 'aria-disabled': ariaDisabled, ...nativeProps }: LoadMoreButtonProps): JSX.Element;
+
+declare type LoadMoreButtonOwnProps = {
     loading?: boolean;
+    loadingLabel?: string;
     noGap?: boolean;
     noBorderRadius?: boolean;
-    onClick?: () => void;
     children: ReactNode;
-}): JSX.Element;
+    ref?: Ref<HTMLButtonElement>;
+};
+
+export declare type LoadMoreButtonProps = LoadMoreButtonOwnProps & Omit<ComponentPropsWithoutRef<'button'>, keyof LoadMoreButtonOwnProps>;
 
 export declare function Menu({ label, entries, withChevron, align, triggerContent }: {
     label: string;
@@ -1021,26 +1106,57 @@ export declare function Menu({ label, entries, withChevron, align, triggerConten
     triggerContent?: ReactNode;
 }): JSX.Element;
 
-export declare type MenuEntry = {
+export declare type MenuEntry = (MenuItemBase & {
+    disabled?: boolean;
+    locked?: false;
+    lockedReason?: never;
+    /** 菜单先完成逻辑关闭，再同步执行该动作；异步状态与后续确认由调用方负责。 */
+    onSelect: () => void;
+}) | (MenuItemBase & {
+    disabled: true;
+    locked?: false;
+    lockedReason?: never;
+    onSelect?: never;
+}) | (MenuItemBase & {
+    disabled?: false;
+    locked: true;
+    /** 锁定原因会并入 menuitem 的可访问名称。 */
+    lockedReason: string;
+    onSelect?: never;
+}) | (MenuLinkBase & {
+    disabled?: false;
+    locked?: false;
+    lockedReason?: never;
+}) | (MenuLinkBase & {
+    disabled: true;
+    locked?: false;
+    lockedReason?: never;
+}) | (MenuLinkBase & {
+    disabled?: false;
+    locked: true;
+    lockedReason: string;
+}) | {
+    type: 'section';
+    label: string;
+} | {
+    type: 'separator';
+};
+
+declare type MenuItemBase = {
     type: 'item';
     label: string;
     icon?: ReactNode;
-    /** 后缀内容（如快捷键提示）；locked 项在未显式传入 suffix 时仍兜底显示锁图标。 */
+    /** 后缀内容（如快捷键提示）；locked 项未显式传入时显示锁定原因。 */
     suffix?: ReactNode;
-    disabled?: boolean;
-    locked?: boolean;
     danger?: boolean;
-} | {
+};
+
+declare type MenuLinkBase = {
     type: 'link';
     label: string;
     href: string;
     icon?: ReactNode;
     suffix?: ReactNode;
-} | {
-    type: 'section';
-    label: string;
-} | {
-    type: 'separator';
 };
 
 export declare function MiddleTruncate({ text, tailLength, mono }: {
@@ -1166,20 +1282,43 @@ declare type NavigationSectionWithLabel = NavigationSectionNativeProps & Omit<Na
     label: NavigationSectionLabel;
 };
 
-export declare function Note({ tone, size, filled, disabled, label, action, children, }: {
+export declare function Note({ tone, size, filled, disabled, label, action, children, }: NoteProps): JSX.Element;
+
+export declare type NoteAction = {
+    type: 'button';
+    label: string;
+    onClick: MouseEventHandler<HTMLButtonElement>;
+    href?: never;
+} | {
+    type: 'link';
+    label: string;
+    href: string;
+    onClick?: never;
+};
+
+export declare type NoteProps = {
     tone?: NoteTone;
     size?: NoteSize;
     filled?: boolean;
     disabled?: boolean;
     label?: string;
-    action?: string;
+    action?: NoteAction;
     children: ReactNode;
-}): JSX.Element;
+};
 
 export declare type NoteSize = 'small' | 'default' | 'large';
 
 export declare type NoteTone = 'info' | 'success' | 'warning' | 'error' | 'secondary';
 
+declare type OptionalButtonAccessibleName = {
+    'aria-label'?: string;
+    /**
+     * @deprecated Deprecated in the unreleased post-0.4.0 migration on 2026-07-20.
+     * Use aria-label. Migration is tracked by #59; removal conditions are in contracts/button-api-compatibility.md.
+     */
+    ariaLabel?: string;
+};
+
 export declare type OverlayCoordinator = {
     register: (entry: ExternalOverlayRegistration) => () => void;
     isTopMost: (id: string) => boolean;
@@ -1224,11 +1363,11 @@ export declare function PeriodCombobox({ presets, activeLabel, onPick, }: {
     onPick: (preset: CalendarPreset) => void;
 }): JSX.Element;
 
-export declare function Phone({ screenLabel }: {
-    screenLabel: string;
+export declare function Phone({ children }: {
+    children: ReactNode;
 }): JSX.Element;
 
-export declare function Pill({ href, size, icon, title, className, children, ...rest }: PillProps): JSX.Element;
+export declare function Pill({ href, size, icon, title, className, children, onBlur, onKeyDown, onLostPointerCapture, onPointerCancel, onPointerDown, onPointerLeave, onPointerUp, ...rest }: PillProps): JSX.Element;
 
 export declare type PillProps = {
     href: string;
@@ -1255,11 +1394,25 @@ export declare type ProgressStop = number | {
     label?: string;
 };
 
-export declare function ProjectBanner({ variant, message, cta }: {
+export declare function ProjectBanner({ variant, message, action }: ProjectBannerProps): JSX.Element;
+
+export declare type ProjectBannerAction = {
+    type: 'button';
+    label: string;
+    onClick: MouseEventHandler<HTMLButtonElement>;
+    href?: never;
+} | {
+    type: 'link';
+    label: string;
+    href: string;
+    onClick?: never;
+};
+
+export declare type ProjectBannerProps = {
     variant?: BannerVariant;
     message: string;
-    cta: string;
-}): JSX.Element;
+    action: ProjectBannerAction;
+};
 
 export declare function Radio({ ...props }: RadioProps): JSX.Element;
 
@@ -1279,22 +1432,34 @@ export declare function RangeField({ layout, trigger, size, minValue, maxValue,
     onChange: (next: RangeValue) => void;
 }): JSX.Element;
 
-export declare function RangeInputs({ value, withTime, onApply, pinnedTimezone, }: {
+export declare function RangeInputs({ value, onApply, pinnedTimezone, }: {
     value: RangeValue;
+    /** 兼容保留；当前组件不提供时间值或时间编辑能力。 */
     withTime: boolean;
     onApply: () => void;
     /** 固定时区：传入时时区从可选 select 变只读文本、不可切换。 */
     pinnedTimezone?: string;
 }): JSX.Element;
 
-export declare function RangeSlider({ min, max, step, defaultLow, defaultHigh, disabled }: {
+export declare const RangeSlider: ForwardRefExoticComponent<RangeSliderProps & RefAttributes<HTMLInputElement>>;
+
+export declare type RangeSliderProps = {
+    label?: string;
+    unit?: string;
     min?: number;
     max?: number;
     step?: number;
-    defaultLow: number;
-    defaultHigh: number;
+    defaultLow?: number;
+    defaultHigh?: number;
+    value?: RangeSliderValue;
+    onValueChange?: (value: RangeSliderValue) => void;
+    id?: string;
+    name?: string;
     disabled?: boolean;
-}): JSX.Element;
+    'aria-describedby'?: string;
+};
+
+export declare type RangeSliderValue = readonly [low: number, high: number];
 
 export declare type RangeValue = {
     start: Date | null;
@@ -1360,29 +1525,44 @@ export declare type SearchDialogTriggerProps = {
     'aria-controls': string;
 };
 
-export declare function SearchInput({ id, ariaLabel, placeholder, defaultValue, disabled, loading, kbdHint, icon, }: {
+export declare function SearchInput({ id, ariaLabel, value: controlledValue, defaultValue, onValueChange, loading, kbdHint, icon, ref, className, disabled, readOnly, autoComplete, spellCheck, onKeyDown: onInputKeyDown, ...inputProps }: SearchInputProps): JSX.Element;
+
+export declare type SearchInputProps = {
     id: string;
-    ariaLabel: string;
-    placeholder: string;
+    /** 无可见 label 时的可访问名；与 FormField 或外部 label 组合时留空。 */
+    ariaLabel?: string;
+    value?: string;
     defaultValue?: string;
-    disabled?: boolean;
+    /** 键入、点击清除和按 Esc 清除共用的值变化通道。 */
+    onValueChange?: (value: string) => void;
     loading?: boolean;
-    kbdHint?: boolean;
+    /** true 显示跨平台 Meta/Ctrl+K；也可传消费方已真实接线的自定义 Kbd 节点。 */
+    kbdHint?: ReactNode;
     icon?: ReactNode;
-}): JSX.Element;
+    /** React 19 ref-as-prop，指向原生 search input。 */
+    ref?: Ref<HTMLInputElement>;
+} & Omit<InputHTMLAttributes<HTMLInputElement>, 'aria-label' | 'defaultValue' | 'id' | 'onChange' | 'ref' | 'type' | 'value'>;
 
-export declare function Select({ id, label, description, error, wide, size, prefix, suffix, className, children, ...rest }: {
+export declare function Select({ id, label, description, error, ref, wide, size, prefix, suffix, className, children, value, defaultValue, multiple, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, ...rest }: {
     id: string;
     label: string;
     description?: string;
     error?: string;
+    /** 指向原生 select（React 19 ref-as-prop），供表单校验后聚焦等场景。 */
+    ref?: Ref<HTMLSelectElement>;
     wide?: boolean;
     size?: FieldSize;
     prefix?: ReactNode;
     /** 装饰性后缀图标（aria-hidden），渲染在下拉箭头左侧；跟 prefix 前缀一样不承载信息，可访问名称仍完全来自 label。 */
     suffix?: ReactNode;
     children: ReactNode;
-} & Omit<SelectHTMLAttributes<HTMLSelectElement>, 'id' | 'children' | 'size' | 'prefix'>): JSX.Element;
+    /** Select 只接受单一值；多值选择使用 MultiSelect。 */
+    value?: string | number;
+    /** Select 只接受单一默认值；多值选择使用 MultiSelect。 */
+    defaultValue?: string | number;
+    /** Select 是单选字段；多值选择使用 MultiSelect。 */
+    multiple?: never;
+} & Omit<SelectHTMLAttributes<HTMLSelectElement>, 'id' | 'children' | 'size' | 'prefix' | 'multiple' | 'value' | 'defaultValue'>): JSX.Element;
 
 export declare function Separator({ orientation, decorative, className, }: {
     orientation?: SeparatorOrientation;
@@ -1411,7 +1591,7 @@ export declare function ShowMore({ items, initial, noBorder, initialExpanded, }:
     items: string[];
     initial?: number;
     noBorder?: boolean;
-    /** 仅用于演示常驻展开态的初始值；组件仍是非受控的，不支持中途从外部切换展开状态。 */
+    /** 仅用于演示初始展开态；组件仍是非受控的，不支持中途从外部切换展开状态。 */
     initialExpanded?: boolean;
 }): JSX.Element;
 
@@ -1465,25 +1645,41 @@ export declare type SidebarSlotProps = HTMLAttributes<HTMLDivElement>;
 
 export declare type SidebarVariant = 'panel' | 'plain';
 
-export declare function Skeleton({ shape, animated, show, className, children, }: {
+export declare function Skeleton({ shape, animated, show, as: Component, className, children, ...rest }: SkeletonProps): JSX.Element;
+
+declare type SkeletonDataAttributes = {
+    [key: `data-${string}`]: string | number | boolean | null | undefined;
+};
+
+export declare type SkeletonProps = {
     shape?: SkeletonShape;
     animated?: boolean;
     /** 包裹模式：数据就绪后置 true，原地显示子内容。 */
     show?: boolean;
+    /** 默认 span 适合短文案与控件；包裹块级内容时显式使用 div。 */
+    as?: 'span' | 'div';
     className?: string;
     children?: ReactNode;
-}): JSX.Element;
+} & Omit<HTMLAttributes<HTMLElement>, 'aria-hidden' | 'children' | 'className'> & SkeletonDataAttributes;
 
 export declare type SkeletonShape = 'rounded' | 'pill' | 'squared';
 
-export declare function Slider({ label, unit, min, max, step, defaultValue }: {
+export declare const Slider: ForwardRefExoticComponent<SliderProps & RefAttributes<HTMLInputElement>>;
+
+export declare type SliderProps = {
     label: string;
     unit: string;
     min?: number;
     max?: number;
     step?: number;
-    defaultValue: number;
-}): JSX.Element;
+    defaultValue?: number;
+    value?: number;
+    onValueChange?: (value: number) => void;
+    id?: string;
+    name?: string;
+    disabled?: boolean;
+    'aria-describedby'?: string;
+};
 
 export declare function Snippet({ text, prompt, inverted, tone, copyText, onCopy, }: {
     text: string | string[];
@@ -1508,7 +1704,7 @@ 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 }: {
+export declare function SplitButton({ label, entries, variant, size, align, menuButtonLabel, icon, disabled, loading, loadingLabel, }: {
     label: string;
     entries: SplitButtonEntry[];
     variant?: 'default' | 'secondary';
@@ -1516,12 +1712,17 @@ export declare function SplitButton({ label, entries, variant, size, align, menu
     align?: 'start' | 'end';
     menuButtonLabel: string;
     icon?: ReactNode;
+    disabled?: boolean;
+    loading?: boolean;
+    loadingLabel?: string;
 }): JSX.Element;
 
 export declare type SplitButtonEntry = {
     label: string;
     danger?: boolean;
     icon?: ReactNode;
+    disabled?: boolean;
+    onSelect?: () => void;
 };
 
 export declare function StatusDot({ tone, label, animated, showLabel, titlePrefix, }: {
@@ -1563,7 +1764,7 @@ export declare type TabItem = {
     content: ReactNode;
     icon?: ReactNode;
     disabled?: boolean;
-    /** 禁用原因（原生 title，桌面端悬浮显示）；放在外层包装上，因为禁用按钮本身在部分浏览器不触发 hover。 */
+    /** 禁用原因；在 tablist 下方常显，并通过 aria-describedby 与禁用标签关联。 */
     tooltip?: string;
 };
 
@@ -1784,6 +1985,7 @@ export declare type UnknownTailPaginationProps = PaginationCommonProps & {
 
 export declare function useCopy(): {
     copied: boolean;
+    pending: boolean;
     copy: (value: string, successMessage?: string) => Promise<void>;
     reset: () => void;
 };
@@ -1826,21 +2028,37 @@ export declare type VerificationCodeInputProps = {
     'aria-label'?: never;
 })));
 
-export declare function Video({ src, poster, tracks, label, controls, loop, }: VideoProps): JSX.Element;
+export declare function Video({ src, poster, tracks, label, purpose, controls, loop, muted, }: VideoProps): JSX.Element;
 
-export declare type VideoProps = {
+declare type VideoBaseProps = {
     /** 视频源，必填。组件不持有任何资产路径——写死默认值会让消费方开箱即拿到不存在的地址。 */
     src: string;
-    /** 首帧海报，兼作弱网/加载失败的兜底画面；缺省时浏览器显示首帧或空白，属合理降级。 */
+    /** 首帧海报；媒体数据尚未加载时保持稳定画面。 */
     poster?: string;
+};
+
+export declare type VideoContentProps = VideoBaseProps & {
+    purpose?: 'content';
     /** 字幕轨；承载信息的视频必须配（见界面准则「媒体可访问」）。 */
     tracks?: VideoTrack[];
     /** 内容视频的可访问名。 */
-    label?: string;
+    label: string;
     controls?: boolean;
     loop?: boolean;
+    muted?: boolean;
 };
 
+export declare type VideoDecorativeProps = VideoBaseProps & {
+    purpose: 'decorative';
+    label?: never;
+    tracks?: never;
+    controls?: false;
+    loop?: true;
+    muted?: true;
+};
+
+export declare type VideoProps = VideoContentProps | VideoDecorativeProps;
+
 /** 字幕/副标题轨；同一组里至多一条 default。 */
 export declare type VideoTrack = {
     /** WebVTT 文件地址。 */