@q1travel/design-system 0.22.0 → 0.23.0

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

@@ -214,6 +214,22 @@ export declare function BrowserTabs({ tabs, className }: {
 
 export declare type BrowserVariant = 'light' | 'dark';
 
+export declare function Bubble({ direction, avatar, name, time, children, status, pending, error, retry, onRetry, actions, className, ...props }: BubbleProps): JSX.Element;
+
+export declare type BubbleProps = Omit<ComponentPropsWithoutRef<'article'>, 'children'> & {
+    direction?: 'incoming' | 'outgoing';
+    avatar?: ReactNode;
+    name?: ReactNode;
+    time?: ReactNode;
+    children: ReactNode;
+    status?: 'default' | 'pending' | 'error';
+    pending?: ReactNode;
+    error?: ReactNode;
+    retry?: ReactNode;
+    onRetry?: () => void;
+    actions?: ReactNode;
+};
+
 export declare function Button(props: ButtonProps): JSX.Element;
 
 declare type ButtonAccessibleName = {
@@ -315,13 +331,12 @@ export declare type ButtonSize = 'sm' | 'md' | 'lg';
 
 export declare type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'warning' | 'danger';
 
-/** 标准日期区间选择器；复用 RangeField 的草稿、弹层和键盘行为。 */
+/** 标准日期与区间选择器；复用 RangeField 的草稿、弹层和键盘行为。 */
 export declare function Calendar(props: CalendarProps): JSX.Element;
 
-export declare function CalendarGrid({ value, onChange, size, minValue, maxValue, today, }: {
-    value: RangeValue;
-    onChange: (next: RangeValue) => void;
+export declare function CalendarGrid(props: CalendarSelectionProps & {
     size?: CalendarSize;
+    withTime?: boolean;
     minValue?: Date;
     maxValue?: Date;
     today?: Date;
@@ -334,6 +349,16 @@ export declare type CalendarPreset = {
 
 export declare type CalendarProps = ComponentProps<typeof RangeField>;
 
+export declare type CalendarSelectionProps = {
+    mode?: 'range';
+    value: RangeValue;
+    onChange: (next: RangeValue) => void;
+} | {
+    mode: 'single';
+    value: Date | null;
+    onChange: (next: Date | null) => void;
+};
+
 export declare type CalendarSize = 'large' | 'small';
 
 export declare function Card(props: CardProps): JSX.Element;
@@ -393,7 +418,7 @@ export declare type ChartProps = {
     className?: string;
 };
 
-export declare function Checkbox({ ...props }: CheckboxProps): JSX.Element;
+export declare function Checkbox({ shape, tone, size, ...props }: CheckboxProps): JSX.Element;
 
 declare type CheckboxOnlyProps = {
     /** 半选：视觉态而非第三个值，由父级逻辑驱动（如"部分子项已选"）。AT 读作 mixed。 */
@@ -401,7 +426,14 @@ declare type CheckboxOnlyProps = {
 };
 
 /** Checkbox 的完整 props。消费方包一层时用它标注，无需知道内部由哪几块组合而成。 */
-export declare type CheckboxProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & ControlOptionNativeInputProps;
+export declare type CheckboxProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & {
+    /** 圆形仅用于任务与清单完成；表单多选保留默认方形。 */
+    shape?: 'square' | 'circle';
+    /** 仅圆形生效；业务方自行映射优先级。 */
+    tone?: 'neutral' | 'info' | 'warning' | 'danger';
+    /** 圆形清单 sm / 详情 md；默认 sm。 */
+    size?: 'sm' | 'md';
+} & Omit<ControlOptionNativeInputProps, 'size'>;
 
 export declare function Choicebox({ type, label, description, extra, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, ...rest }: ChoiceboxProps): JSX.Element;
 
@@ -596,7 +628,11 @@ export declare type CommandMenuSection = {
     items: CommandMenuItem[];
 };
 
-export declare function Composer({ onSubmit, onAttach, attachments, mentions, disabled, }: ComposerProps): JSX.Element;
+export declare function Composer({ onSubmit, onAttach, attachments, mentions, commands, onCommand, disabled, }: ComposerProps): JSX.Element;
+
+export declare type ComposerCommand = ComposerMention & {
+    keywords?: string[];
+};
 
 export declare type ComposerMention = {
     id: string;
@@ -606,7 +642,9 @@ export declare type ComposerMention = {
 
 export declare type ComposerProps = {
     onSubmit: (submission: ComposerSubmission) => void;
-    onAttach?: () => void;
+    onAttach?: (() => void) | ((files: File[]) => void);
+    commands?: ComposerCommand[];
+    onCommand?: (id: string, argumentText: string) => void;
     attachments?: ReactNode;
     mentions?: ComposerMention[];
     disabled?: boolean;
@@ -865,6 +903,9 @@ export declare function EmptyState({ icon, title, description, actions, headingL
     headingLevel?: 2 | 3 | 4 | 5 | 6;
 }): JSX.Element;
 
+/** Public host for consumer-owned sibling portals. Package overlays share this Foundation root. */
+export declare function ensurePopoverRoot(): HTMLElement | null;
+
 export declare function Entity({ leading, title, subtitle, trailing, }: {
     leading?: ReactNode;
     title: string;
@@ -963,7 +1004,12 @@ export declare type FileTreeNode = {
 };
 
 /** 筛选选择器入口；弹层、筛选值与 expanded 状态归调用方。 */
-export declare function FilterChip({ label, value, onClear, disabled, className, ...props }: FilterChipProps): JSX.Element;
+export declare const FilterChip: ForwardRefExoticComponent<    {
+label: string;
+/** undefined 表示未设置；0、空字符串和 null 仍是已设置。 */
+value?: ReactNode;
+onClear?: () => void;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "value"> & RefAttributes<HTMLButtonElement>>;
 
 export declare type FilterChipProps = {
     label: string;
@@ -998,6 +1044,21 @@ 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;
 
+/** Hoverable supplemental information; activation belongs to the trigger. */
+export declare function HoverCard({ trigger, children, openDelay, closeDelay, side, align, className }: HoverCardProps): JSX.Element;
+
+export declare type HoverCardProps = {
+    /** A named native button, or a component forwarding native button attributes. */
+    trigger: ReactElement<ButtonHTMLAttributes<HTMLButtonElement>>;
+    /** Supplemental, noninteractive content; essential information belongs in the page. */
+    children: ReactNode;
+    openDelay?: number;
+    closeDelay?: number;
+    side?: PopoverSide;
+    align?: PopoverAlign;
+    className?: string;
+};
+
 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 = {
@@ -1193,7 +1254,7 @@ export declare function Marker({ actor, time, variant, children, }: MarkerProps)
 export declare type MarkerProps = {
     actor?: ReactNode;
     time?: ReactNode;
-    variant?: 'default' | 'separator';
+    variant?: 'default' | 'separator' | 'unread';
     children: ReactNode;
 };
 
@@ -1265,7 +1326,7 @@ declare type MenuLinkBase = {
     suffix?: ReactNode;
 };
 
-export declare function Message({ author, avatar, time, children, attachments, actions, status, onRetry, }: MessageProps): JSX.Element;
+export declare function Message({ author, avatar, time, children, attachments, actions, acknowledgements, status, onRetry, }: MessageProps): JSX.Element;
 
 export declare type MessageProps = {
     author: ReactNode;
@@ -1274,10 +1335,31 @@ export declare type MessageProps = {
     children: ReactNode;
     attachments?: ReactNode;
     actions?: ReactNode;
+    acknowledgements?: ReactNode;
     status?: 'default' | 'pending' | 'failed';
     onRetry?: () => void;
 };
 
+export declare function MessageScroller({ label, items, conversationKey, nearBottomThreshold, announcement, jumpLabel, before, empty, className, style }: MessageScrollerProps): JSX.Element;
+
+export declare type MessageScrollerItem = {
+    id: string | number;
+    content: ReactNode;
+};
+
+export declare type MessageScrollerProps = {
+    label: string;
+    items: readonly MessageScrollerItem[];
+    conversationKey?: string | number;
+    nearBottomThreshold?: number;
+    announcement?: string;
+    jumpLabel?: string;
+    before?: ReactNode;
+    empty?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+};
+
 export declare function MiddleTruncate({ text, tailLength, mono }: {
     text: string;
     tailLength?: number;
@@ -1520,8 +1602,60 @@ export declare type PillProps = {
     title?: string;
 } & AnchorHTMLAttributes<HTMLAnchorElement>;
 
+export declare function Popover({ open: controlledOpen, defaultOpen, onOpenChange, onClose, trigger, anchorRef, children, side, align, placement: requestedPlacement, modal, ariaModal, role: requestedRole, ariaLabel, ariaLabelledBy, ariaDescribedBy, offset, matchWidth, selectedValue, initialFocus, id: suppliedId, className, dismissExcludeRefs }: PopoverProps): JSX.Element;
+
+export declare type PopoverAlign = 'start' | 'center' | 'end';
+
+export declare type PopoverInitialFocus = 'first' | 'last' | 'none';
+
 export declare type PopoverLayout = 'vertical' | 'horizontal';
 
+export declare type PopoverPlacement = 'auto' | 'auto-end' | 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+
+export declare type PopoverProps = PopoverSharedProps & (({
+    trigger: ReactNode;
+    anchorRef?: never;
+    open?: boolean;
+    defaultOpen?: boolean;
+} & ({
+    ariaLabel: string;
+    ariaLabelledBy?: never;
+} | {
+    ariaLabel?: never;
+    ariaLabelledBy: string;
+})) | {
+    trigger?: never;
+    anchorRef: RefObject<HTMLElement | null>;
+    open: boolean;
+    defaultOpen?: never;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+});
+
+export declare type PopoverRole = 'dialog' | 'menu' | 'listbox';
+
+declare type PopoverSharedProps = {
+    children: ReactNode;
+    onOpenChange?: (open: boolean) => void;
+    onClose?: () => void;
+    placement?: PopoverPlacement;
+    side?: PopoverSide;
+    align?: PopoverAlign;
+    role?: PopoverRole;
+    modal?: boolean;
+    ariaModal?: boolean;
+    ariaDescribedBy?: string;
+    offset?: number;
+    matchWidth?: boolean | number;
+    selectedValue?: string | number;
+    initialFocus?: PopoverInitialFocus;
+    id?: string;
+    className?: string;
+    dismissExcludeRefs?: ReadonlyArray<RefObject<HTMLElement | null>>;
+};
+
+export declare type PopoverSide = 'bottom' | 'top' | 'left' | 'right';
+
 export declare function ProductLockup({ name, icon, brand, size, className, 'aria-label': ariaLabel, ...rest }: ProductLockupProps): JSX.Element;
 
 export declare type ProductLockupProps = {
@@ -1577,7 +1711,7 @@ export declare function Radio({ ...props }: RadioProps): JSX.Element;
 /** Radio 的完整 props。 */
 export declare type RadioProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & ControlOptionNativeInputProps;
 
-export declare function RangeField({ layout, trigger, size, fieldSize, minValue, maxValue, pinnedTimezone, today, value, onChange, }: {
+export declare function RangeField(props: CalendarSelectionProps & {
     layout?: PopoverLayout;
     trigger?: TriggerKind;
     size?: CalendarSize;
@@ -1586,18 +1720,18 @@ export declare function RangeField({ layout, trigger, size, fieldSize, minValue,
     minValue?: Date;
     maxValue?: Date;
     pinnedTimezone?: string;
-    /** 透传给内部 CalendarGrid（默认真实当前日期）；文档 demo 传固定值保持演示可控。 */
     today?: Date;
-    value: RangeValue;
-    onChange: (next: RangeValue) => void;
+    /** 显式启用本地 24 小时时间编辑；默认仅选择日期。 */
+    withTime?: boolean;
 }): JSX.Element;
 
-export declare function RangeInputs({ value, onApply, pinnedTimezone, }: {
+export declare function RangeInputs(props: (CalendarSelectionProps | {
+    mode?: 'range';
     value: RangeValue;
-    /** 兼容保留；当前组件不提供时间值或时间编辑能力。 */
+    onChange?: (next: RangeValue) => void;
+}) & {
     withTime: boolean;
     onApply: () => void;
-    /** 固定时区：传入时时区从可选 select 变只读文本、不可切换。 */
     pinnedTimezone?: string;
 }): JSX.Element;
 
@@ -1732,13 +1866,15 @@ export declare function Separator({ orientation, decorative, className, }: {
 
 export declare type SeparatorOrientation = 'horizontal' | 'vertical';
 
-export declare function Sheet({ open, onClose, title, side, size, dismissable, children, footer }: {
+export declare function Sheet({ open, onClose, title, side, size, dismissable, mobileFullscreen, children, footer }: {
     open: boolean;
     onClose: () => void;
     title: string;
     side?: SheetSide;
     size?: SheetSize;
     dismissable?: boolean;
+    /** 窄屏全视口面板；默认保留浮层间距。 */
+    mobileFullscreen?: boolean;
     children: ReactNode;
     footer?: ReactNode;
 }): ReactNode;
@@ -2051,6 +2187,13 @@ export declare type ThresholdTone = 'primary' | 'success' | 'warning' | 'danger'
 
 export declare function Timeline({ className, ...props }: TimelineProps): JSX.Element;
 
+export declare function TimelineCollapsedGroup({ summary, children }: TimelineCollapsedGroupProps): JSX.Element;
+
+export declare type TimelineCollapsedGroupProps = {
+    summary: ReactNode;
+    children: ReactNode;
+};
+
 export declare function TimelineItem({ tone, indicator, children, className, ...props }: TimelineItemProps): JSX.Element;
 
 export declare type TimelineItemProps = HTMLAttributes<HTMLLIElement> & {
@@ -2107,6 +2250,42 @@ export declare function Toggle({ checked, defaultOn, onChange, disabled, size, o
     ariaLabel?: string;
 }): JSX.Element;
 
+export declare function ToggleGroup(props: ToggleGroupProps): JSX.Element;
+
+declare type ToggleGroupBaseProps = {
+    items: ToggleGroupItem[];
+    ariaLabel: string;
+    size?: ButtonSize;
+    disabled?: boolean;
+};
+
+export declare type ToggleGroupItem = {
+    value: string;
+    disabled?: boolean;
+} & ({
+    label: string;
+    icon?: ReactNode;
+    ariaLabel?: string;
+} | {
+    label?: never;
+    icon: ReactNode;
+    ariaLabel: string;
+});
+
+export declare type ToggleGroupProps = ToggleGroupBaseProps & ({
+    type: 'single';
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    allowEmpty?: boolean;
+} | {
+    type: 'multiple';
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+    allowEmpty?: never;
+});
+
 export declare type ToggleSize = 'sm' | 'md' | 'lg';
 
 export declare function Toolbar({ 'aria-label': ariaLabel, orientation, children, className, }: ToolbarProps): JSX.Element;