@q1travel/design-system 0.29.1 → 0.30.0

package/contracts/design.dark.md

@@ -480,7 +480,7 @@ These components ship in the package. Compose from this list before writing new
 - IconButton requires an accessible name. An icon-only control without one is not deliverable.
 - CornerRemoveButton is a fixed 24px corner removal control for thumbnails, avatars, and tags; require a caller-provided aria-label. Wrap the host and button in `.q1-corner-anchor`; reserve space around the host and avoid clipping the shared 44px coarse-pointer hit region. This does not extend the Button size scale.
 
-**Text fields.** FormField, Label, InfoTip, Input, ClearableInput, SearchInput, InputOTP, Textarea, Select, Fieldset, ErrorMessage.
+**Text fields.** FormField, Label, RequiredIndicator, InfoTip, Input, ClearableInput, SearchInput, InputOTP, Textarea, Select, Fieldset, ErrorMessage.
 
 - InputOTP collects a fixed six-digit code in one joined group by default; `separator` explicitly enables 3+3 groups. VerificationCodeInput and VerificationCodeInputProps remain deprecated aliases for one minor version; migrate to InputOTP and InputOTPProps before their removal in the next minor version. The old `/components/verification-code-input` route redirects to `/components/input-otp`.
 - FormField owns the label, help text, and error slot. Do not assemble those three around a bare Input.
@@ -488,7 +488,7 @@ These components ship in the package. Compose from this list before writing new
 - FormField positions its visually hidden label and empty live status within its own containing block so an overflowing inline row cannot enlarge the page scroll width.
 - Select is for a short, fixed list. Anything searchable, or longer than roughly seven entries, is a Combobox.
 
-**Option fields.** ControlOption, Checkbox, Radio, Choicebox, Combobox, MultiSelect, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
+**Option fields.** ControlOption, Checkbox, Radio, Choicebox, Combobox, MultiSelect, MultiCombobox, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
 
 **Checkbox task completion circle.** `Checkbox` adds `shape?: 'square' | 'circle'` (default square). Circle-only `tone?: 'neutral' | 'info' | 'warning' | 'danger'` defaults to neutral; `size?: 'sm' | 'md'` defaults to sm. 圆形只用于任务与清单的完成场景；表单多选一律用方形。 Native checkbox, ref, bare accessible names and Space activation remain intact; Enter does not toggle. Circle rejects indeterminate with a development warning. `readOnly` remains focusable, exposes aria-disabled and prevents toggles, hover previews and press feedback; completed readonly circles keep a desaturated fill and tick.
 

package/contracts/design.md

@@ -480,7 +480,7 @@ These components ship in the package. Compose from this list before writing new
 - IconButton requires an accessible name. An icon-only control without one is not deliverable.
 - CornerRemoveButton is a fixed 24px corner removal control for thumbnails, avatars, and tags; require a caller-provided aria-label. Wrap the host and button in `.q1-corner-anchor`; reserve space around the host and avoid clipping the shared 44px coarse-pointer hit region. This does not extend the Button size scale.
 
-**Text fields.** FormField, Label, InfoTip, Input, ClearableInput, SearchInput, InputOTP, Textarea, Select, Fieldset, ErrorMessage.
+**Text fields.** FormField, Label, RequiredIndicator, InfoTip, Input, ClearableInput, SearchInput, InputOTP, Textarea, Select, Fieldset, ErrorMessage.
 
 - InputOTP collects a fixed six-digit code in one joined group by default; `separator` explicitly enables 3+3 groups. VerificationCodeInput and VerificationCodeInputProps remain deprecated aliases for one minor version; migrate to InputOTP and InputOTPProps before their removal in the next minor version. The old `/components/verification-code-input` route redirects to `/components/input-otp`.
 - FormField owns the label, help text, and error slot. Do not assemble those three around a bare Input.
@@ -488,7 +488,7 @@ These components ship in the package. Compose from this list before writing new
 - FormField positions its visually hidden label and empty live status within its own containing block so an overflowing inline row cannot enlarge the page scroll width.
 - Select is for a short, fixed list. Anything searchable, or longer than roughly seven entries, is a Combobox.
 
-**Option fields.** ControlOption, Checkbox, Radio, Choicebox, Combobox, MultiSelect, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
+**Option fields.** ControlOption, Checkbox, Radio, Choicebox, Combobox, MultiSelect, MultiCombobox, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
 
 **Checkbox task completion circle.** `Checkbox` adds `shape?: 'square' | 'circle'` (default square). Circle-only `tone?: 'neutral' | 'info' | 'warning' | 'danger'` defaults to neutral; `size?: 'sm' | 'md'` defaults to sm. 圆形只用于任务与清单的完成场景；表单多选一律用方形。 Native checkbox, ref, bare accessible names and Space activation remain intact; Enter does not toggle. Circle rejects indeterminate with a development warning. `readOnly` remains focusable, exposes aria-disabled and prevents toggles, hover previews and press feedback; completed readonly circles keep a desaturated fill and tick.
 

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

@@ -1568,7 +1568,57 @@ declare type ModalLegacyDismissalProps = {
 
 export declare type ModalProps = ModalBaseProps & (ModalLegacyDismissalProps | ModalEscapeActionProps);
 
-export declare function MultiSelect({ options: rawOptions, defaultSelected, placeholder, onChange, preserveSelectionOrder }: MultiSelectProps): JSX.Element;
+/** 标签触发器与弹层搜索组合；选项变更保持展开，选中值完全受控。 */
+export declare function MultiCombobox({ options, value, onChange, onOpenChange, selectedOptions, placeholder, searchPlaceholder, onSearch, searchValue, isLoading, loadError, onRetry, emptyText, disabled, readOnly, invalid, errorId, error, clearable, id, name, className, ref, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, 'aria-describedby': ariaDescribedby }: MultiComboboxProps): JSX.Element;
+
+export declare type MultiComboboxChangeDetails = {
+    action: 'select' | 'remove' | 'clear';
+    option?: MultiComboboxOption;
+};
+
+export declare type MultiComboboxOption = {
+    value: string;
+    label: string;
+    /** 同值可有多个匹配行；rowKey 在本次结果中唯一，提交仍使用 value。 */
+    rowKey?: string;
+    description?: string;
+    keywords?: string[];
+    disabled?: boolean;
+};
+
+export declare type MultiComboboxProps = {
+    options: MultiComboboxOption[];
+    value: string[];
+    onChange: (values: string[], details?: MultiComboboxChangeDetails) => void;
+    /** 通知所有开闭路径；调用方可在关闭时清理远端搜索。 */
+    onOpenChange?: (open: boolean) => void;
+    /** 选中标签的规范名称，与搜索结果、停用状态解耦；缺失时按 options / value 回退。 */
+    selectedOptions?: Pick<MultiComboboxOption, 'value' | 'label'>[];
+    placeholder: string;
+    searchPlaceholder?: string;
+    /** 存在时 options 是服务端结果，不再本地过滤；查询保留到调用方清除。 */
+    onSearch?: (query: string) => void;
+    searchValue?: string;
+    isLoading?: boolean;
+    loadError?: ReactNode;
+    onRetry?: () => void;
+    emptyText?: ReactNode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    invalid?: boolean;
+    errorId?: string;
+    error?: string;
+    clearable?: boolean;
+    id?: string;
+    name?: string;
+    className?: string;
+    ref?: Ref<HTMLButtonElement>;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+};
+
+export declare function MultiSelect({ options: rawOptions, defaultSelected, placeholder, onChange, preserveSelectionOrder, value, disabled, readOnly, id, ref, invalid, errorId, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, 'aria-describedby': ariaDescribedby }: MultiSelectProps): JSX.Element;
 
 export declare type MultiSelectOption = {
     /** 选中值：写入 defaultSelected / onChange，同一组内唯一。 */
@@ -1581,13 +1631,24 @@ export declare type MultiSelectProps = {
     /** 纯字符串选项的值与显示文本相同；值与显示文本不同时传 { value, label }。 */
     options: ReadonlyArray<string | MultiSelectOption>;
     defaultSelected?: string[];
+    /** 存在时由调用方持有选中值；defaultSelected 仅用于非受控初值。 */
+    value?: string[];
+    disabled?: boolean;
+    readOnly?: boolean;
+    id?: string;
+    ref?: Ref<HTMLButtonElement>;
+    invalid?: boolean;
+    errorId?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
     placeholder: string;
     onChange?: (next: string[]) => void;
     /** 全选时保留已选项的先后顺序，只把未选项按列表顺序追加到末尾；默认 false，全选按列表顺序重排。 */
     preserveSelectionOrder?: boolean;
 };
 
-export declare function Navigation({ className, orientation, variant, ...props }: NavigationProps): JSX.Element;
+export declare function Navigation({ className, orientation, variant, children, ...props }: NavigationProps): JSX.Element;
 
 export declare function NavigationGroup({ label, icon, expanded, defaultExpanded, onExpandedChange, children, }: NavigationGroupProps): JSX.Element;
 
@@ -1973,6 +2034,8 @@ export declare function RelativeTimeCard({ relative, relativeLong, iso, local, u
     utc: string;
 }): JSX.Element;
 
+export declare function RequiredIndicator(): JSX.Element;
+
 export declare function Scroller({ axis, label, children, }: {
     axis: Axis;
     label: string;
@@ -2236,7 +2299,7 @@ export declare function Spinner({ size, tone, label, }: {
 
 export declare type SpinnerSize = 'sm' | 'md' | 'lg' | 'xl';
 
-export declare type SpinnerTone = 'default' | 'danger' | 'success' | 'info';
+export declare type SpinnerTone = 'default' | 'danger' | 'success' | 'info' | 'inherit';
 
 export declare function SplitButton({ label, entries, variant, size, align, menuButtonLabel, icon, disabled, loading, loadingLabel, }: {
     label: string;