@q1travel/design-system 0.31.3 → 0.31.4

package/contracts/button-api-compatibility.md

@@ -46,7 +46,7 @@ Under `prefers-reduced-motion: reduce`, no attention animation runs and the stat
 
 | State | Button | ButtonLink | Label and status |
 | --- | --- | --- | --- |
-| `loading` | Keeps the existing `aria-disabled="true"` and `tabIndex=0` focusable contract; does not add `aria-busy` or native `disabled` unless `disabled` was also passed. | Removes `href`, keeps `aria-disabled="true"` and `tabIndex=0` so the loading state remains discoverable. | Keeps the original visible children and announces `loadingLabel` through the existing internal `role="status"` spinner. |
+| `loading` | Keeps the existing `aria-disabled="true"` and `tabIndex=0` focusable contract; does not add `aria-busy` or native `disabled` unless `disabled` was also passed. | Removes `href`, keeps `aria-disabled="true"` and `tabIndex=0` so the loading state remains discoverable. | Preserves the original children and affix layout as visually hidden size placeholders, retains the accessible name, and centers an overlaid spinner announcing `loadingLabel` through the existing internal `role="status"`. Width, height, and position remain unchanged. |
 | `busy` | Uses native `disabled`, sets `aria-busy="true"`, and blocks clicks. | Removes `href`, sets `aria-disabled="true"`, `aria-busy="true"`, `tabIndex=-1`, and blocks clicks. | Shows one spinner. A non-empty `busyLabel` replaces the visible label without replacing the stable accessible name; a separate polite `role="status"` announces `busyLabel`, then `loadingLabel`, then `正在处理…`. |
 | `busy + loading` | Busy wins; one spinner and the busy interaction contract apply. | Busy wins; the link is not navigable or focusable. | `busyLabel` wins for visible/status text; `loadingLabel` is only a fallback when busyLabel is empty. |
 

package/contracts/design.dark.md

@@ -413,6 +413,11 @@ components:
 ---
 # q1travel Design System
 
+只读值用 text-primary、禁用值用 text-muted、只读占位用 text-secondary（亮暗均 ≥4.5:1），disabled 优先。禁用文字在真实背景对比至少 3:1 且弱于可用态；禁用图标保留既有颜色。
+
+Combobox、MultiSelect、Cascader 可用态仅在精细指针悬停时加深描边（亮 gray-800、暗 gray-700），底色不变；聚焦、只读、禁用与 invalid 不响应悬停。状态修复覆盖全部尺寸，尺寸与字级统一仅限 md。
+Combobox 的 `showSelectedPrefix?: boolean` 默认 false；开启时只在选中项有 prefix 且未输入编辑时显示装饰前置内容（aria-hidden），无 prefix 不留空位。选中前置槽 sm/md/lg 分别使用 space-5/space-6/space-7（20/24/28），编辑态搜索槽等宽，图标保持原尺寸并居中。Combobox 选中值、MultiSelect 触发摘要与 Cascader 单选值单行省略，实际截断时悬停显示全文；输入聚焦编辑使用原生滚动，Cascader 多选标签不变。
+
 ## Overview
 
 This is the dark-theme source contract. It keeps token names aligned with the light contract and changes values only where the theme requires a different surface, text, border, or status value.
@@ -504,6 +509,7 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 
 
 - Toggle represents one on/off setting and reports a requested change immediately. Square Checkbox stages a form change that a submit applies; circle Checkbox marks task completion through the consumer’s change handler. Choosing the wrong one misstates when the change takes effect.
+- Toggle 默认关闭轨道在亮暗主题均用 `gray-700` 填充、`gray-800` 悬停填充；暗色无边框，圆点保持 `action-on-primary`。三尺寸在面板与页面底上的非禁用轨道边界/父底及圆点边界/轨道均至少 3:1；悬停轨道/父底不弱于常态且颜色不同。开启保留主操作色，禁用保留整体 0.5 透明度；按压轨道保持对应悬停色，圆点增加既有 `--q1-shadow-popover` 阴影；轨道与圆点均无额外缩放或位移，释放恢复。
 - Switch selects among mutually exclusive views or modes; its outer sm / md / lg heights are 32 / 40 / 48px on fine pointers, defaulting to md. Optional `variant="cards"` provides equal-width wrapping cards with a left-aligned label-12 label above caller-owned `meta` (number or ReactNode) in regular label-14 tabular figures, space-2 padding/gap and content-driven equal sm/md/lg height; cards alone use a two-pixel border-active selected border and inset line without a tint, a matching border-active label and the complete shared keyboard focus ring; disabled selected cards keep a neutral two-pixel border-strong outline with muted text, so the selection stays distinguishable. An auto-fit grid keeps any item count and its last row equally wide, with a readable 10rem minimum; the four-item example uses 全部 / 需要处理 / 更新 / 已归档 with numeric counts 128 / 12 / 8 / 32; the default `segmented` markup, dimensions and keyboard/radio semantics remain unchanged.
 - ToggleGroup uses pressed buttons for single or multiple choices; arrow keys move focus without selecting. Icon-only items require an accessible name. See `implementation-map.md` for selection ownership.
 - RangeSlider is two thumbs over one interval, paired with numeric inputs; Slider is a single value.

package/contracts/design.md

@@ -415,6 +415,11 @@ components:
 ---
 # q1travel Design System
 
+只读值用 text-primary、禁用值用 text-muted、只读占位用 text-secondary（亮暗均 ≥4.5:1），disabled 优先。禁用文字在真实背景对比至少 3:1 且弱于可用态；禁用图标保留既有颜色。
+
+Combobox、MultiSelect、Cascader 可用态仅在精细指针悬停时加深描边（亮 gray-800、暗 gray-700），底色不变；聚焦、只读、禁用与 invalid 不响应悬停。状态修复覆盖全部尺寸，尺寸与字级统一仅限 md。
+Combobox 的 `showSelectedPrefix?: boolean` 默认 false；开启时只在选中项有 prefix 且未输入编辑时显示装饰前置内容（aria-hidden），无 prefix 不留空位。选中前置槽 sm/md/lg 分别使用 space-5/space-6/space-7（20/24/28），编辑态搜索槽等宽，图标保持原尺寸并居中。Combobox 选中值、MultiSelect 触发摘要与 Cascader 单选值单行省略，实际截断时悬停显示全文；输入聚焦编辑使用原生滚动，Cascader 多选标签不变。
+
 ## Overview
 
 This is the light-theme source contract. It defines token names, semantic roles, and component mappings before documentation examples are rendered.
@@ -506,6 +511,7 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 
 
 - Toggle represents one on/off setting and reports a requested change immediately. Square Checkbox stages a form change that a submit applies; circle Checkbox marks task completion through the consumer’s change handler. Choosing the wrong one misstates when the change takes effect.
+- Toggle 默认关闭轨道在亮暗主题均用 `gray-700` 填充、`gray-800` 悬停填充；暗色无边框，圆点保持 `action-on-primary`。三尺寸在面板与页面底上的非禁用轨道边界/父底及圆点边界/轨道均至少 3:1；悬停轨道/父底不弱于常态且颜色不同。开启保留主操作色，禁用保留整体 0.5 透明度；按压轨道保持对应悬停色，圆点增加既有 `--q1-shadow-popover` 阴影；轨道与圆点均无额外缩放或位移，释放恢复。
 - Switch selects among mutually exclusive views or modes; its outer sm / md / lg heights are 32 / 40 / 48px on fine pointers, defaulting to md. Optional `variant="cards"` provides equal-width wrapping cards with a left-aligned label-12 label above caller-owned `meta` (number or ReactNode) in regular label-14 tabular figures, space-2 padding/gap and content-driven equal sm/md/lg height; cards alone use a two-pixel border-active selected border and inset line without a tint, a matching border-active label and the complete shared keyboard focus ring; disabled selected cards keep a neutral two-pixel border-strong outline with muted text, so the selection stays distinguishable. An auto-fit grid keeps any item count and its last row equally wide, with a readable 10rem minimum; the four-item example uses 全部 / 需要处理 / 更新 / 已归档 with numeric counts 128 / 12 / 8 / 32; the default `segmented` markup, dimensions and keyboard/radio semantics remain unchanged.
 - ToggleGroup uses pressed buttons for single or multiple choices; arrow keys move focus without selecting. Icon-only items require an accessible name. See `implementation-map.md` for selection ownership.
 - RangeSlider is two thumbs over one interval, paired with numeric inputs; Slider is a single value.

package/contracts/implementation-map.md

@@ -150,7 +150,7 @@ Accepted 2026-10-08: explicitly sized single-line Button, ButtonLink, Input, Sea
 
 Owner approved 2026-10-15 (#455): public `RegionErrorState` replaces only a region whose data request failed, while the host keeps its frame (table header, card title, section heading). Props: `title` (required), `description`, `layout` `center` (default; table bodies and large regions, block padding `--q1-space-16` keeps roughly five table rows of height) or `inline` (cards and page sections; the retry button wraps under the description when the component's own container is narrower than 30rem), `headingLevel` 2–6 (default renders `p`, matching EmptyState), `onRetry`, `retrying`, and `live` `polite` (default, `role=status`) or `assertive` (`role=alert`). Accepted 2026-10-25 (#659): `strip` adds `.region-error-state--strip`, a full-width neutral strip with `--q1-color-bg-hover`, `--q1-radius-2`, block padding `--q1-space-2`, inline padding `--q1-space-4`, and minimum block size twice `--q1-space-6`. It shares inline typography and announcements, but its retry always stays inside the right edge without the narrow-container wrap. There is no `size` prop.
 
-The announcement region wraps only the icon, the `q1-sr-only` 「错误：」 prefix, the title and the description, and carries `aria-busy` while `retrying`. The retry Button sits outside that region so its loading status never nests inside another live region. Retry uses Button `loading` (focusable, `aria-disabled`, polite 「正在重试」 status) rather than `busy` (native disabled drops focus); the component stays mounted while retrying, and the visible label swaps 「重试」 to 「正在重试」 (hidden from assistive technology because the loading status already announces it). Icons are rendered internally from the existing icon set (AlertCircle, RotateCcw); no icon is exported. Copy is caller-owned; field errors, 403/404 and backend messages are out of scope. After a successful retry the caller moves focus to the restored content. Existing tokens only; the danger color appears only on the icon.
+The announcement region wraps only the icon, the `q1-sr-only` 「错误：」 prefix, the title and the description, and carries `aria-busy` while `retrying`. The retry Button sits outside that region so its loading status never nests inside another live region. Retry uses Button `loading` (focusable, `aria-disabled`, polite 「正在重试」 status) rather than `busy` (native disabled drops focus); the component stays mounted while retrying, and the children remain 「重试」 to preserve the exact idle width and height. While retrying, the existing `aria-label` names the button 「正在重试」; idle omits that attribute. The shared Button loading rule visually hides that content and shows only its centered spinner; the accessible name remains 「正在重试」, and one loading status announces it. Icons are rendered internally from the existing icon set (AlertCircle, RotateCcw); no icon is exported. Copy is caller-owned; field errors, 403/404 and backend messages are out of scope. After a successful retry the caller moves focus to the restored content. Existing tokens only; the danger color appears only on the icon.
 
 ## Cascader 层级选择
 

package/contracts/interface-guidelines.md

@@ -103,6 +103,8 @@ Adding a clause therefore means answering two questions before the wording: who
 - [both] MUST pair normal text over an image with fully opaque `--q1-color-text-on-media` and `--q1-color-media-scrim` covering the entire text background, or an independently verified opaque text backing. Do not assume `overlay-scrim` provides text contrast. Verify at least 4.5:1 after actual composition; translucent text, parent opacity, filters, blending and gradients require their own measurement.
 - [both] MUST caption spoken audio and provide a transcript for any media that carries information not available in surrounding text.
 
+- [both] CopyButton, TextWithCopyButton, and Snippet success keep the existing check and announcement channel (CopyButton/Snippet inline status; TextWithCopyButton success Toast) and displays an aria-hidden Check +「已复制」bubble for 2 seconds using the shared anchored overlay and 浮层面（与 Popover/Menu 相同）. Changing the value clears both; failures keep the existing error feedback. The bubble 优先在按钮下方，空间不足时换到上方；it escapes overflow clipping without changing button layout; it does not enter the overlay stack or intercept the enclosing surface’s Escape or outside-pointer dismissal.
+
 ## Accessibility Tiers
 
 Every component is classified into one accessibility tier; the tier sets its bar. The tier is decided by how much keyboard and focus behavior the component must own beyond native semantics. The keyboard model source is always the matching WAI-ARIA APG pattern, not invention — established design systems follow APG too, so "matching a reference" and "following APG" do not conflict.

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

@@ -369,7 +369,7 @@ declare type ButtonSharedProps = {
     shortcut?: string;
     className?: string;
     children?: ReactNode;
-    /** 文字前置图标槽；14–16px、currentColor，装饰性（自带 aria-hidden）。loading 时被 spinner 接管。 */
+    /** 文字前置图标槽；14–16px、currentColor，装饰性（自带 aria-hidden）。loading 时保留占位并视觉隐藏。 */
     prefix?: ReactNode;
     /** 文字后置图标槽，同上。 */
     suffix?: ReactNode;
@@ -692,7 +692,7 @@ export declare function CollapsibleBreadcrumb({ items, label, linkComponent }: {
     linkComponent?: LinkComponent;
 }): JSX.Element;
 
-export declare function Combobox({ options, searchPlacement, searchPlaceholder, footer, value, onChange, onSearch, isLoading, placeholder, size, required, 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, showSelectedPrefix, searchPlaceholder, footer, value, onChange, onSearch, isLoading, placeholder, size, required, 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 层保证）。 */
@@ -714,6 +714,8 @@ export declare type ComboboxProps = {
     options: ComboboxOption[];
     /** 默认在触发器输入；panel 使用按钮触发并将搜索放在弹层。 */
     searchPlacement?: 'input' | 'panel';
+    /** 为 true 时选中值前显示该选项的 prefix；选项无 prefix 时不留空位。 */
+    showSelectedPrefix?: boolean;
     /** 面板搜索的独立占位文案。 */
     searchPlaceholder?: string;
     /** 列表之外的操作区，进入正常 Tab 顺序。 */
@@ -2243,7 +2245,7 @@ export declare type RegionErrorStateProps = {
     headingLevel?: 2 | 3 | 4 | 5 | 6;
     /** 传入时渲染「重试」按钮；不传则不提供重试。 */
     onRetry?: () => void;
-    /** 重试进行中：组件原地保留，按钮进入载入态并显示「正在重试」，焦点留在按钮上。 */
+    /** 重试进行中：组件原地保留，按钮进入载入态并播报「正在重试」，焦点留在按钮上。 */
     retrying?: boolean;
     /** 出现时的播报级别：polite 用 role=status，assertive 用 role=alert。默认 polite。 */
     live?: 'polite' | 'assertive';