@q1travel/design-system 0.7.2 → 0.8.0

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

@@ -204,6 +204,10 @@ declare type ButtonBaseProps = {
     loading?: boolean;
     /** loading 时 role=status 播报的文案，默认"加载中…"；仅供屏幕阅读器，不影响可见文案。 */
     loadingLabel?: string;
+    /** 已提交忙态：原生禁用 + aria-busy，阻止重复提交。 */
+    busy?: boolean;
+    /** busy 时的可见状态文案；为空时保留原始 children，并用 loadingLabel 或固定 fallback 播报。 */
+    busyLabel?: string;
     disabled?: boolean;
     type?: 'button' | 'submit' | 'reset';
     shortcut?: string;
@@ -238,6 +242,7 @@ export declare type ButtonLinkProps = Omit<ButtonBaseProps, 'type'> & {
     onFocus?: FocusEventHandler<HTMLAnchorElement>;
     onBlur?: FocusEventHandler<HTMLAnchorElement>;
     onKeyDown?: KeyboardEventHandler<HTMLAnchorElement>;
+    'aria-keyshortcuts'?: string;
     ref?: Ref<HTMLAnchorElement>;
 };
 
@@ -630,7 +635,19 @@ export declare function DestructiveActionModal({ open, onClose, title, descripti
     /** 提交进行中：双按钮禁用、主操作显示加载指示；open 由调用方控制，加载中模态保持打开。 */
     loading?: boolean;
     onConfirm: () => string | null;
-}): JSX.Element | null;
+}): ReactNode;
+
+export declare type DocsPageLink = {
+    title: string;
+    href: string;
+};
+
+export declare function DocsPagination({ previous, next }: DocsPaginationProps): JSX.Element;
+
+export declare type DocsPaginationProps = {
+    previous?: DocsPageLink;
+    next?: DocsPageLink;
+};
 
 export declare function DotsMenu({ entries, size, disabled, align, }: {
     entries: DotsMenuEntry[];
@@ -653,7 +670,7 @@ export declare function Drawer({ open, onClose, title, children, footer, height,
     footer: ReactNode;
     /** 面板最大高度（px），覆盖默认 60vh；仅当默认高度会裁切主操作时使用。 */
     height?: number;
-}): JSX.Element | null;
+}): ReactNode;
 
 export declare function EmptyState({ icon, title, description, actions, headingLevel, }: {
     icon?: ReactNode;
@@ -824,6 +841,18 @@ export declare function Kbd({ meta, shift, alt, ctrl, small, children, }: {
     children?: ReactNode;
 }): JSX.Element;
 
+export declare type KnownTotalPaginationProps = PaginationCommonProps & ({
+    total: number;
+    totalPages?: never;
+    hasNextPage?: never;
+    showPageNumbers?: boolean;
+} | {
+    total?: never;
+    totalPages: number;
+    hasNextPage?: never;
+    showPageNumbers?: boolean;
+});
+
 export declare function Label({ htmlFor, required, children, }: {
     htmlFor?: string;
     required?: boolean;
@@ -892,7 +921,7 @@ export declare function Modal({ open, onClose, title, children, footer, initialF
     dismissable?: boolean;
     /** 头尾固定、只有正文区域滚动；用于正文可能超出视口高度的场景（长列表、长条款）。 */
     sticky?: boolean;
-}): JSX.Element | null;
+}): ReactNode;
 
 export declare function ModalInset({ children }: {
     children: ReactNode;
@@ -992,14 +1021,31 @@ declare type NoteSize = 'small' | 'default' | 'large';
 
 export declare type NoteTone = 'info' | 'success' | 'warning' | 'error' | 'secondary';
 
-declare type PageLink = {
-    title: string;
+export declare function Pagination({ page, pageSize: pageSizeProp, total, totalPages: totalPagesProp, hasNextPage, onChange, loading, showPageNumbers, summary, pageSizeSlot, prevLabel, nextLabel, compact, className, }: PaginationProps): JSX.Element;
+
+declare type PaginationCommonProps = {
+    page: number;
+    pageSize?: number;
+    onChange: (page: number) => void;
+    loading?: boolean;
+    summary?: ReactNode | ((args: PaginationSummaryArgs) => ReactNode);
+    pageSizeSlot?: ReactNode;
+    prevLabel?: string;
+    nextLabel?: string;
+    compact?: boolean;
+    className?: string;
 };
 
-export declare function Pagination({ previous, next }: {
-    previous?: PageLink;
-    next?: PageLink;
-}): JSX.Element;
+export declare type PaginationProps = KnownTotalPaginationProps | UnknownTailPaginationProps;
+
+export declare type PaginationSummaryArgs = {
+    page: number;
+    totalPages?: number;
+    total?: number;
+    pageSize: number;
+    start: number;
+    end: number;
+};
 
 export declare function PeriodCombobox({ presets, activeLabel, onPick, }: {
     presets: CalendarPreset[];
@@ -1179,7 +1225,7 @@ export declare function Sheet({ open, onClose, title, side, children, footer }:
     side?: SheetSide;
     children: ReactNode;
     footer?: ReactNode;
-}): JSX.Element | null;
+}): ReactNode;
 
 export declare type SheetSide = 'top' | 'right' | 'bottom' | 'left';
 
@@ -1280,11 +1326,12 @@ export declare function StatusDot({ tone, label, animated, showLabel, titlePrefi
 
 export declare type StatusDotTone = 'neutral' | 'warning' | 'success' | 'danger';
 
-export declare function Switch({ options, ariaLabel, name, defaultValue, onChange, size, fullWidth, iconOnly, }: {
+export declare function Switch({ options, ariaLabel, name, defaultValue, value, onChange, size, fullWidth, iconOnly, }: {
     options: SwitchOption[];
     ariaLabel: string;
     name?: string;
     defaultValue?: string;
+    value?: string;
     onChange?: (value: string) => void;
     size?: 'sm' | 'md' | 'lg';
     fullWidth?: boolean;
@@ -1296,8 +1343,9 @@ export declare type SwitchOption = {
     value: string;
     label: string;
     icon?: ReactNode;
+    meta?: ReactNode;
     disabled?: boolean;
-    /** 补充说明（原生 title，桌面端悬浮显示）；用于图标模式下文字看不出来的额外上下文。 */
+    /** 补充说明；用于在标签旁提供低强调度的上下文。 */
     tooltip?: string;
 };
 
@@ -1365,7 +1413,7 @@ export declare function ToastProvider({ children }: {
 
 export declare type ToastTone = 'default' | 'success' | 'warning' | 'error';
 
-export declare function Toggle({ checked, defaultOn, onChange, disabled, size, onColor, label, description, labelSide, ariaLabel, }: {
+export declare function Toggle({ checked, defaultOn, onChange, disabled, size, onColor, label, description, labelSide, 'aria-label': canonicalAriaLabel, 'aria-labelledby': ariaLabelledBy, ariaLabel, }: {
     /** 受控值；提供后内部状态失效，显示值以外部回写的 checked 为准。 */
     checked?: boolean;
     /** 非受控模式的初始值；与 checked 同传时以 checked 为准。 */
@@ -1378,6 +1426,9 @@ export declare function Toggle({ checked, defaultOn, onChange, disabled, size, o
     label?: string;
     description?: string;
     labelSide?: 'left' | 'right';
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    /** @deprecated 使用 aria-label。 */
     ariaLabel?: string;
 }): JSX.Element;
 
@@ -1414,6 +1465,13 @@ declare type TooltipTriggerProps = {
 
 export declare type TriggerKind = 'default' | 'compact';
 
+export declare type UnknownTailPaginationProps = PaginationCommonProps & {
+    total?: never;
+    totalPages?: never;
+    hasNextPage: boolean;
+    showPageNumbers?: false;
+};
+
 export declare function useCopy(): {
     copied: boolean;
     copy: (value: string, successMessage?: string) => Promise<void>;