@q1travel/design-system 0.26.0 → 0.27.0

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

@@ -1,4 +1,5 @@
 import { AnchorHTMLAttributes } from 'react';
+import { AriaRole } from 'react';
 import { ButtonHTMLAttributes } from 'react';
 import { ComponentProps } from 'react';
 import { ComponentPropsWithoutRef } from 'react';
@@ -47,6 +48,29 @@ export declare interface AuthCardProps {
 
 export declare function Avatar({ title, src, letter, glyph, placeholder, icon, iconColor, size, className }: AvatarProps): JSX.Element;
 
+export declare function AvatarButton({ label, src, children, size, href, onClick, editIndicator, className, ref, ...rest }: AvatarButtonProps): JSX.Element;
+
+export declare type AvatarButtonProps = {
+    /** 可访问名，必填，如「更换组织图标」。 */
+    label: string;
+    /** 图块图片；与 children 二选一，同时提供时以 src 为准。 */
+    src?: string;
+    /** 图块内容（字母、图标或 Avatar）。 */
+    children?: ReactNode;
+    /** 图块边长像素；缺省 32。 */
+    size?: number;
+    /** 提供时渲染为链接。 */
+    href?: string;
+    onClick?: MouseEventHandler<HTMLAnchorElement | HTMLButtonElement>;
+    /** 悬停 / 焦点时显示铅笔徽标；缺省 true。 */
+    editIndicator?: boolean;
+    className?: string;
+    role?: AriaRole;
+    tabIndex?: number;
+    ref?: Ref<HTMLAnchorElement | HTMLButtonElement>;
+    [dataAttribute: `data-${string}`]: string | number | boolean | null | undefined;
+};
+
 export declare function AvatarGroup({ members, label, size, limit, overlap, reverse, className, }: {
     members: AvatarMember[];
     /** 可选整组名；传入则套 role=group 作整组增强，不传则默认逐个头像标注（读屏念每个成员名）。 */
@@ -749,6 +773,15 @@ export declare type ContextSwitcherAction = {
     textValue: string;
     icon?: ReactNode;
     disabled?: boolean;
+    /** 单层子菜单；带 children 的动作本身不触发回调，只有叶子触发。 */
+    children?: ContextSwitcherAction[];
+};
+
+export declare type ContextSwitcherAvatarAction = {
+    /** 可访问名，如「更换组织图标」。 */
+    label: string;
+    href?: string;
+    onSelect?: () => void;
 };
 
 export declare type ContextSwitcherCurrent = {
@@ -774,6 +807,11 @@ export declare type ContextSwitcherGroup = {
     divider?: boolean;
 };
 
+export declare type ContextSwitcherHeader = ContextSwitcherCurrent & {
+    /** 提供时头部头像渲染为可编辑的 AvatarButton，并成为头部第一个菜单项。 */
+    avatarAction?: ContextSwitcherAvatarAction;
+};
+
 export declare type ContextSwitcherItem = {
     id: string;
     label: ReactNode;
@@ -784,12 +822,19 @@ export declare type ContextSwitcherItem = {
     disabled?: boolean;
     depth?: 0 | 1;
     kind?: 'context' | 'action';
+    /** 行尾附注（如计数），仅视觉呈现；读屏文本由 metaLabel 提供。 */
+    meta?: ReactNode;
+    /** meta 的可读文本，并入该项的 aria-describedby。 */
+    metaLabel?: string;
+    /** 仅 kind 为 action 时可用：单层子菜单，叶子项通过 onFooterAction 通知。 */
+    children?: ContextSwitcherAction[];
 };
 
 export declare type ContextSwitcherPresentation = {
     type?: 'grouped';
 } | {
     type: 'stacked';
+    nesting?: 'indent' | 'flush';
 } | {
     type: 'drilldown';
     primaryGroupId: string;
@@ -806,7 +851,7 @@ export declare type ContextSwitcherProps = {
     pendingId?: string;
     errorMessage?: ReactNode;
     footerActions?: ContextSwitcherAction[];
-    header?: ContextSwitcherCurrent;
+    header?: ContextSwitcherHeader;
     headerActions?: ContextSwitcherAction[];
     onFooterAction?: (action: ContextSwitcherAction) => void;
     label?: string;
@@ -990,6 +1035,14 @@ declare type FieldBareProps = {
     error?: never;
 };
 
+export declare type FieldLabelHintProps = {
+    label: string;
+    labelHint?: ReactNode;
+} | {
+    label?: never;
+    labelHint?: never;
+};
+
 export declare type FieldLabelVisibilityProps = {
     label: string;
     labelHidden?: boolean;
@@ -1081,9 +1134,11 @@ export declare type FilterOptionPanelProps = {
     onQueryChange?: (query: string) => void;
 };
 
-export declare function FormField({ controlId, label, labelHidden, description, error, wide, children, }: {
+export declare function FormField({ controlId, label, labelHidden, labelHint, description, error, wide, children, }: {
     controlId: string;
     label?: string;
+    /** 规则释义/字段注解：渲染为标签旁的 InfoTip，不在字段下占位；标签隐藏时不渲染。 */
+    labelHint?: ReactNode;
     description?: string;
     error?: string;
     wide?: boolean;
@@ -1157,7 +1212,16 @@ export declare type IconButtonProps = IconButtonAccessibleName & IconButtonBaseP
     ref?: Ref<HTMLButtonElement>;
 };
 
-export declare function Input({ id, label, labelHidden, description, error, invalid, errorId, ref, prefix, suffix, prefixStyling, suffixStyling, rounded, wide, size, className, revealable, revealed, onRevealedChange, revealLabel, hideLabel, disabled, ...rest }: {
+export declare function InfoTip({ label, content }: InfoTipProps): JSX.Element;
+
+export declare type InfoTipProps = {
+    /** 被说明对象的名称；可访问名为「{label}说明」。 */
+    label: string;
+    /** 说明内容：一句规则释义或字段注解。 */
+    content: ReactNode;
+};
+
+export declare function Input({ id, label, labelHidden, labelHint, 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)）。 */
@@ -1194,9 +1258,9 @@ export declare function Input({ id, label, labelHidden, description, error, inva
     rounded?: boolean;
     wide?: boolean;
     size?: FieldSize;
-} & (FieldShellProps | FieldBareProps) & FieldLabelVisibilityProps & Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'size' | 'prefix'>): JSX.Element;
+} & (FieldShellProps | FieldBareProps) & FieldLabelVisibilityProps & FieldLabelHintProps & Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'size' | 'prefix'>): JSX.Element;
 
-export declare function InputOTP({ id, name, value, onValueChange, disabled, readOnly, required, invalid, errorId, size, separator, ref, label, labelHidden, description, error, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': describedBy, }: InputOTPProps): JSX.Element;
+export declare function InputOTP({ id, name, value, onValueChange, disabled, readOnly, required, invalid, errorId, size, separator, ref, label, labelHidden, labelHint, description, error, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': describedBy, }: InputOTPProps): JSX.Element;
 
 export declare type InputOTPProps = {
     id?: string;
@@ -1214,7 +1278,7 @@ export declare type InputOTPProps = {
     separator?: boolean;
     ref?: Ref<HTMLInputElement>;
     'aria-describedby'?: string;
-} & FieldLabelVisibilityProps & ((FieldShellProps & {
+} & FieldLabelVisibilityProps & FieldLabelHintProps & ((FieldShellProps & {
     'aria-label'?: never;
     'aria-labelledby'?: never;
 }) | (FieldBareProps & ({
@@ -1267,9 +1331,10 @@ export declare type KnownTotalPaginationProps = PaginationCommonProps & ({
     showPageNumbers?: boolean;
 });
 
-export declare function Label({ htmlFor, required, children, }: {
+export declare function Label({ htmlFor, required, hint, children, }: {
     htmlFor?: string;
     required?: boolean;
+    hint?: ReactNode;
     children: string;
 }): JSX.Element;
 
@@ -1331,7 +1396,7 @@ declare type MentionQuery = (query: string, options: {
     signal: AbortSignal;
 }) => Promise<ComposerMention[]>;
 
-export declare function Menu({ label, entries, withChevron, align, triggerContent, size }: {
+export declare function Menu({ label, entries, withChevron, align, triggerContent, prefix, size }: {
     label: string;
     /** 文字触发器尺寸，默认 md；图标触发器保留原尺寸。 */
     size?: ButtonSize;
@@ -1340,6 +1405,8 @@ export declare function Menu({ label, entries, withChevron, align, triggerConten
     align?: 'start' | 'end';
     /** 自定义触发器内容（如纯图标）；label 始终作为可访问名称的兜底，图标-only 时经 aria-label 暴露。 */
     triggerContent?: ReactNode;
+    /** 文字触发器的前置图标，与 Button 的 prefix 一致；仍按文字触发器的尺寸与内边距渲染，传了 triggerContent 时忽略。 */
+    prefix?: ReactNode;
 }): JSX.Element;
 
 export declare type MenuEntry = (MenuItemBase & {
@@ -1788,6 +1855,14 @@ export declare function RangeField(props: CalendarSelectionProps & {
     today?: Date;
     /** 显式启用本地 24 小时时间编辑；默认仅选择日期。 */
     withTime?: boolean;
+    /** 透传到触发器按钮，供外部 `<label htmlFor>` 关联或表单定位。 */
+    id?: string;
+    /** 触发器的可访问名称；未提供时读出触发器上的可见文字。 */
+    'aria-label'?: string;
+    /** 用页面上已有元素命名触发器。 */
+    'aria-labelledby'?: string;
+    /** 禁用触发器与清除操作，弹层不可打开。 */
+    disabled?: boolean;
 }): JSX.Element;
 
 export declare function RangeInputs(props: (CalendarSelectionProps | {
@@ -1904,7 +1979,7 @@ export declare type SearchInputProps = {
     ref?: Ref<HTMLInputElement>;
 } & Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'aria-label' | 'defaultValue' | 'id' | 'onChange' | 'ref' | 'type' | 'value'>;
 
-export declare function Select({ id, label, labelHidden, description, error, ref, wide, size, prefix, suffix, className, children, value, defaultValue, multiple, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, ...rest }: {
+export declare function Select({ id, label, labelHidden, labelHint, 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;
@@ -1923,7 +1998,7 @@ export declare function Select({ id, label, labelHidden, description, error, ref
     defaultValue?: string | number;
     /** Select 是单选字段；多值选择使用 MultiSelect。 */
     multiple?: never;
-} & FieldLabelVisibilityProps & Omit<SelectHTMLAttributes<HTMLSelectElement>, 'id' | 'children' | 'size' | 'prefix' | 'multiple' | 'value' | 'defaultValue'>): JSX.Element;
+} & FieldLabelVisibilityProps & FieldLabelHintProps & Omit<SelectHTMLAttributes<HTMLSelectElement>, 'id' | 'children' | 'size' | 'prefix' | 'multiple' | 'value' | 'defaultValue'>): JSX.Element;
 
 export declare function Separator({ orientation, decorative, className, }: {
     orientation?: SeparatorOrientation;
@@ -2123,7 +2198,10 @@ export declare type SwitchOption = {
 export declare type TabItem = {
     id: string;
     label: string;
-    content: ReactNode;
+    /** 组件内面板内容；省略且未给 panelId 时不渲染面板。 */
+    content?: ReactNode;
+    /** 页面内由您自己渲染的区块 id；提供时 aria-controls 指向它，组件不再渲染自带面板。 */
+    panelId?: string;
     icon?: ReactNode;
     disabled?: boolean;
     /** 禁用原因；在 tablist 下方常显，并通过 aria-describedby 与禁用标签关联。 */
@@ -2208,13 +2286,13 @@ export declare type TableSortDirection = 'asc' | 'desc';
 export declare function Tabs({ tabs, ariaLabel, variant, value, defaultValue, onValueChange, }: {
     tabs: TabItem[];
     ariaLabel: string;
-    variant?: 'default' | 'secondary';
+    variant?: 'default' | 'secondary' | 'line';
     value?: string;
     defaultValue?: string;
     onValueChange?: (id: string) => void;
 }): JSX.Element | null;
 
-export declare function Textarea({ id, label, labelHidden, description, error, invalid, errorId, ref, wide, size, className, maxLength, onInput, ...rest }: TextareaProps): JSX.Element;
+export declare function Textarea({ id, label, labelHidden, labelHint, description, error, invalid, errorId, ref, wide, size, className, maxLength, onInput, ...rest }: TextareaProps): JSX.Element;
 
 /** Textarea 的完整 props。消费方包一层时用它标注，无需知道内部由哪几块组合而成。 */
 export declare type TextareaProps = {
@@ -2228,7 +2306,7 @@ export declare type TextareaProps = {
     ref?: Ref<HTMLTextAreaElement>;
     wide?: boolean;
     size?: FieldSize;
-} & (FieldShellProps | FieldBareProps) & FieldLabelVisibilityProps & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'id'>;
+} & (FieldShellProps | FieldBareProps) & FieldLabelVisibilityProps & FieldLabelHintProps & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'id'>;
 
 export declare function TextWithCopyButton({ text, copyValue, successMessage, size, }: {
     text: string;