@q1travel/design-system 0.30.1-next.60 → 0.30.2

package/contracts/design.dark.md

@@ -133,6 +133,7 @@ semantic-colors:
   surface-overlay: "{colors.gray-300}"
   surface-hover: "color-mix(in srgb, var(--q1-color-text-primary) 6%, transparent)"
   surface-selected: "#1f1e38"
+  surface-selected-neutral: "{colors.gray-300}"
   surface-inverse: "{colors.gray-1000}"
   text-on-inverse: "#0a0a0a"
   surface-media: "#0a0a0a"
@@ -488,7 +489,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, MultiCombobox, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
+**Option fields.** ControlOption, Checkbox, Radio, RadioGroup, 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

@@ -133,6 +133,7 @@ semantic-colors:
   surface-overlay: "{colors.background-100}"
   surface-hover: "color-mix(in srgb, var(--q1-color-text-primary) 4%, transparent)"
   surface-selected: "{colors.primary-100}"
+  surface-selected-neutral: "{colors.gray-300}"
   surface-inverse: "{colors.gray-1000}"
   text-on-inverse: "{colors.background-100}"
   surface-media: "#0a0a0a"
@@ -488,7 +489,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, MultiCombobox, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
+**Option fields.** ControlOption, Checkbox, Radio, RadioGroup, 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/overlay-shadow-migration.md

@@ -43,6 +43,24 @@ Decision date: 2026-08-26
 
 方向性面板（Drawer / Sheet）的阴影在组件内自持，不消费这两个 token，因此不受影响。
 
+## 2026-10-21 浅色浮层补齐贴边淡影与浅底环
+
+`--q1-shadow-popover` 浅色主题由三层补齐为五层，自上而下：
+
+1. `0 0 0 1px` `--q1-color-gray-alpha-200`（黑 8%）：边缘环。
+2. `0 1px 1px` 黑 2%：贴边淡影。
+3. `0 4px 8px -4px` 黑 4%：接触层。
+4. `0 16px 24px -8px` 黑 6%：环境层。
+5. `0 0 0 1px` `--q1-color-background-200`：边缘环下方的浅底环。
+
+暗色取值与 `--q1-shadow-modal` 均不变。
+
+**为什么加贴边淡影**：边缘环只有 1px 且各向均匀，下缘缺少紧贴边界的过渡，接触层又偏远；`0 1px 1px` 的 2% 淡影让下缘更利落，不增加整体重量。
+
+**为什么加浅底环**：半透明的黑 8% 边缘环会透出其下方的页面底色，在白底与灰底上呈现的环色不同。边缘环下方垫一圈 `background-200`，环色基本不随页面底色漂移，灰底上的边界更稳定。
+
+**为什么环强度保持 8%**：该 token 与通用边框一致，是发丝线，强度低于相邻控件描边，不抢层级；边界清晰度由新增两层补足，而不是继续加深环。
+
 ## 下游影响面
 
 2026-08-26 对下游消费方的只读检索结果：`--q1-shadow-popover` 下游消费点 2 处，`--q1-shadow-modal` 下游消费点 0 处。

package/contracts/token-naming.md

@@ -93,6 +93,7 @@ Examples:
 
 - `--q1-color-bg-canvas`
 - `--q1-color-bg-panel`
+- `--q1-color-bg-selected-neutral`
 - `--q1-color-text-primary`
 - `--q1-color-border`
 - `--q1-color-action-primary`
@@ -104,6 +105,8 @@ Examples:
 
 `--q1-color-border-warning` and `--q1-color-bg-warning-subtle` name the warning border and subtle background by role. They are equivalent to the existing `--q1-color-status-warning-border` and `--q1-color-status-warning-surface`; the background uses amber-100 in both themes, matching the success/danger subtle-surface mapping. Existing status names remain valid. Use `--q1-color-status-warning-text` on the subtle background for AA normal text. The border is a quiet decorative outline, not a standalone control boundary or the sole warning cue; pair it with warning text or an icon.
 
+`--q1-color-bg-selected-neutral` is the opaque neutral current-item background, separate from the branded `bg-selected`, quiet `bg-subtle`, and transient `bg-hover`. It references existing `gray-300` in both light and dark mode. Default, secondary, and ghost Button selected states consume it while retaining border and `aria-pressed` cues and using a heavier font weight than unselected controls; primary selected retains its primary press color, and warning/danger selected retains `bg-subtle`. The neutral selected background has measured DeltaE00 >= 3 against resting canvas, panel, and subtle surfaces in both themes; no separation from transient hover is required. Consumers may adopt the new role without renaming existing tokens; revert the Button background references and remove this additive role to roll back.
+
 Owner-approved exception (2026-10-05): ErrorMessage, field errors, and ErrorCard titles use `--q1-color-red-900`; other status text retains its existing semantic text token.
 
 `--q1-color-focus` is neutral black in light mode and white in dark mode. `--q1-shadow-focus` and `--q1-shadow-focus-input` use a gapless 1px ring at 34% plus a 4px halo at 16%. Buttons and inputs consume this recipe; input focus preserves the resting border, without an active-border swap or inset stroke. `--q1-input-border-focus` remains an opt-in override and defaults to the resting input border. Invalid inputs retain their danger border; `--q1-shadow-focus-input-danger` and `--q1-shadow-focus-danger` use the same 1px / 4px geometry with danger color at 34% / 16%. Text links retain the 3px neutral focus underline. Forced colors and high contrast retain visible system outlines.
@@ -209,6 +212,16 @@ ship with values, because the pre-mixed colors exist nowhere else; `Table` still
 a fallback (`bg-canvas`, `bg-subtle`, `bg-selected`) so a stylesheet without them keeps an opaque
 row. A table on a surface other than the canvas overrides all four on the table or its container.
 
+`Table` also exposes `--q1-table-header-bg` for every header cell, including sticky headers
+and sticky-column intersections. Without an override, ordinary headers retain their transparent
+background; sticky headers retain `var(--q1-table-row-bg)` (then
+`var(--q1-color-bg-canvas)` when row tokens are absent). Like the input customization slots,
+it is intentionally not defined at the root, preserving both existing defaults and table-local
+row background overrides. Set it on the table or its container to `var(--q1-color-bg-subtle)`
+for a subtle header; every header then uses that same color, while body row and selection
+backgrounds remain independent. Existing tables need no migration. Remove the override to
+restore the corresponding default.
+
 Every component token MUST declare a fallback to the semantic token it replaces, so a
 consumer that defines none of them sees no change. A component token without a fallback
 turns an opt-in customisation surface into a required one: the first consumer to upgrade

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

@@ -1,10 +1,12 @@
 import { AnchorHTMLAttributes } from 'react';
 import { AriaRole } from 'react';
 import { ButtonHTMLAttributes } from 'react';
+import { ChangeEvent } from 'react';
 import { ComponentProps } from 'react';
 import { ComponentPropsWithoutRef } from 'react';
 import { ComponentPropsWithRef } from 'react';
 import { CSSProperties } from 'react';
+import { FieldsetHTMLAttributes } from 'react';
 import { FocusEventHandler } from 'react';
 import { ForwardRefExoticComponent } from 'react';
 import { HTMLAttributes } from 'react';
@@ -505,7 +507,7 @@ export declare type ClearableInputProps = {
     ref?: Ref<HTMLInputElement>;
 } & Omit<InputHTMLAttributes<HTMLInputElement>, 'aria-label' | 'defaultValue' | 'id' | 'ref' | 'type' | 'value'>;
 
-export declare function ClearButton({ className, label, onClick, ...buttonProps }: {
+export declare function ClearButton({ className, label, onClick, onMouseDown, ...buttonProps }: {
     className: string;
     label: string;
     onClick: () => void;
@@ -578,13 +580,14 @@ export declare function CollapsibleBreadcrumb({ items, label }: {
     label: string;
 }): JSX.Element;
 
-export declare function Combobox({ options, value, onChange, onSearch, isLoading, placeholder, size, disabled, readOnly, invalid, errorId, error, emptyText, clearable, id, className, name, inputMode, spellCheck, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ref, ...rest }: ComboboxProps): JSX.Element;
+export declare function Combobox({ options, searchPlacement, searchPlaceholder, footer, value, onChange, onSearch, isLoading, placeholder, size, disabled, readOnly, invalid, errorId, error, emptyText, clearable, id, className, name, inputMode, spellCheck, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ref, ...rest }: ComboboxProps): JSX.Element;
 
 export declare type ComboboxOption = {
     /** 禁止空字符串（与「未选」的受控空值歧义，adapter 层保证）。 */
     value: string;
     /** 显示与过滤的唯一来源。 */
     label: string;
+    description?: string;
     disabled?: boolean;
     /** 组件透而不读，仅随 onChange 第二参原样带回。 */
     meta?: unknown;
@@ -597,6 +600,12 @@ export declare type ComboboxOption = {
 export declare type ComboboxProps = {
     /** 唯一 shape，后端字段在 adapter 层转换。 */
     options: ComboboxOption[];
+    /** 默认在触发器输入；panel 使用按钮触发并将搜索放在弹层。 */
+    searchPlacement?: 'input' | 'panel';
+    /** 面板搜索的独立占位文案。 */
+    searchPlaceholder?: string;
+    /** 列表之外的操作区，进入正常 Tab 顺序。 */
+    footer?: ReactNode;
     /** 受控选中值；'' = 未选。 */
     value: string;
     /** 选中传 (option.value, option)；clearable 清除传 ('', undefined)。 */
@@ -1532,6 +1541,8 @@ export declare function Modal(props: ModalProps): ReactNode;
 declare type ModalBaseProps = {
     open: boolean;
     title: string;
+    /** 标题下方的一行导语；读屏打开对话框时随标题一并读出。不传则不渲染。 */
+    description?: ReactNode;
     children: ReactNode;
     footer: ReactNode;
     initialFocusRef?: RefObject<HTMLElement | null>;
@@ -1569,7 +1580,7 @@ declare type ModalLegacyDismissalProps = {
 export declare type ModalProps = ModalBaseProps & (ModalLegacyDismissalProps | ModalEscapeActionProps);
 
 /** 标签触发器与弹层搜索组合；选项变更保持展开，选中值完全受控。 */
-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 function MultiCombobox({ options, value, onChange, onOpenChange, selectedOptions, placeholder, searchPlaceholder, onSearch, searchValue, isLoading, loadError, onRetry, emptyText, footer, required, 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';
@@ -1603,6 +1614,8 @@ export declare type MultiComboboxProps = {
     loadError?: ReactNode;
     onRetry?: () => void;
     emptyText?: ReactNode;
+    footer?: ReactNode;
+    required?: boolean;
     disabled?: boolean;
     readOnly?: boolean;
     invalid?: boolean;
@@ -1903,7 +1916,7 @@ export declare type ProductLockupProps = {
 export declare type ProductLockupSize = 'sm' | 'md';
 
 export declare function Progress({ value, max, tone, slim, stops, label, }: {
-    value: number;
+    value: number | null;
     max?: number;
     tone?: 'neutral' | ThresholdTone;
     slim?: boolean;
@@ -1940,6 +1953,40 @@ export declare function Q1travelSymbol(props: SVGProps<SVGSVGElement>): JSX.Elem
 
 export declare function Radio({ ...props }: RadioProps): JSX.Element;
 
+export declare function RadioGroup({ label, labelHidden, options, name, value, defaultValue, onChange, disabled, required, description, error, form, id, className, 'aria-describedby': ariaDescribedBy, ...fieldsetProps }: RadioGroupProps): JSX.Element;
+
+export declare type RadioGroupOption = {
+    value: string;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+};
+
+export declare type RadioGroupProps = Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, 'onChange' | 'defaultValue' | 'children' | 'name' | 'form'> & {
+    /** 组名，渲染为 legend；与 Label 同一视觉。 */
+    label: string;
+    /** 视觉隐藏组名，读屏仍读出（用于上下文已给出标题的场景）。 */
+    labelHidden?: boolean;
+    options: RadioGroupOption[];
+    /** 原生 radio 的 name；缺省自动生成，同表单内提交时显式传入。 */
+    name?: string;
+    /** 受控值；与 defaultValue 二选一。 */
+    value?: string;
+    defaultValue?: string;
+    /** 选中项变化时回调，参数为新选中项的 value。 */
+    onChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
+    /** 整组禁用，原生 fieldset 级联禁用所有选项。 */
+    disabled?: boolean;
+    /** 必选：组名后显示必填标记，选项带原生 required。 */
+    required?: boolean;
+    /** 组名下方的补充说明。 */
+    description?: string;
+    /** 组级错误，显示在最后一个选项之后。 */
+    error?: string;
+    /** 表单归属，透传给每个选项。 */
+    form?: string;
+};
+
 /** Radio 的完整 props。 */
 export declare type RadioProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & FieldLabelVisibilityProps & ControlOptionNativeInputProps;
 
@@ -2049,12 +2096,18 @@ export declare function ScrollerWithButtons({ axis, contentName, label, children
     children: ReactNode;
 }): JSX.Element;
 
-export declare function SearchDialog({ open, onOpenChange, query, onQueryChange, sections, onSelect, renderTrigger, label, placeholder, emptyTitle, clearQueryLabel, }: SearchDialogProps): JSX.Element;
+export declare function SearchDialog({ open, onOpenChange, query, onQueryChange, sections, onSelect, renderTrigger, label, placeholder, emptyTitle, clearQueryLabel, footer, }: SearchDialogProps): JSX.Element;
 
 export declare type SearchDialogItem = {
     id: string;
     label: string;
     description?: string;
+    /** 装饰性前置图标；不参与选项名称。 */
+    icon?: ReactNode;
+    /** 非交互式尾注。 */
+    suffix?: ReactNode;
+    /** 仅展示快捷键；实际绑定由调用方负责。 */
+    keybind?: string;
     disabled?: boolean;
     /**
      * 标记当前项（例如站内搜索里的当前页面）：选项输出 aria-current 并显示勾选标记，
@@ -2075,12 +2128,15 @@ export declare type SearchDialogProps = {
     placeholder?: string;
     emptyTitle?: string;
     clearQueryLabel?: string;
+    footer?: ReactNode;
 };
 
 export declare type SearchDialogSection = {
     id: string;
     heading?: string;
     items: SearchDialogItem[];
+    /** 选项集合外的加载、错误或重试内容；播报语义由调用方提供。 */
+    status?: ReactNode;
 };
 
 export declare type SearchDialogTriggerProps = {