@q1travel/design-system 0.28.0 → 0.29.0

package/contracts/button-api-compatibility.md

@@ -28,6 +28,8 @@ Button and IconButton accept native button props, ARIA attributes, `data-*` attr
 
 Package-owned semantics are applied after native props. `type`, `className`, `disabled`, busy/loading `aria-disabled`/`aria-busy`/`tabIndex`, the resolved accessible name, `ref`, and the busy/loading click guards therefore keep their documented behavior. Outside busy/loading, a consumer-provided `tabIndex` or `aria-disabled` remains intact. The canonical native `aria-keyshortcuts` value wins over the compatibility `ariaKeyshortcuts` field by nullish precedence.
 
+Button preserves an explicitly supplied native `aria-busy` when `busy` is false, including during `loading`; `loading` alone still does not add it. This lets consumers announce an external task immediately while controlling visual loading separately. `busy=true` always sets `aria-busy="true"`, even when a consumer passes false. ButtonLink keeps its existing package-owned busy semantics.
+
 ## Loading and Busy States
 
 `loading` and `busy` are intentionally different public states:

package/contracts/implementation-map.md

@@ -105,7 +105,7 @@ Timeline / TimelineItem (ol/li, 8px token dot or Avatar), Marker (quiet actor/ti
 
 ## ToggleGroup selection ownership
 
-Accepted 2026-10-07: public `ToggleGroup` uses the shadcn/Radix name (no corresponding industry-common component). Its `items` API exposes `value`, `label`, optional `icon`, `disabled`, and `ariaLabel`; icon-only items require an icon and `ariaLabel`. `type="single"` accepts string `value` / `defaultValue` and `onValueChange`; `allowEmpty` defaults to false. `type="multiple"` accepts string arrays. Controlled values remain caller-owned; uncontrolled single selection falls back to the first enabled item when its value is absent or unknown and empty selection is disallowed. Disabling an existing selected item retains its pressed state and moves only the tabstop. No existing Switch consumer is migrated.
+Accepted 2026-10-07: public `ToggleGroup` names a group of pressable controls with single or multiple selection. Its `items` API exposes `value`, `label`, optional `icon`, `disabled`, and `ariaLabel`; icon-only items require an icon and `ariaLabel`. `type="single"` accepts string `value` / `defaultValue` and `onValueChange`; `allowEmpty` defaults to false. `type="multiple"` accepts string arrays. Controlled values remain caller-owned; uncontrolled single selection falls back to the first enabled item when its value is absent or unknown and empty selection is disallowed. Disabling an existing selected item retains its pressed state and moves only the tabstop. No existing Switch consumer is migrated.
 
 Native buttons expose `aria-pressed` within `role="group"`. Roving tabindex and Arrow / Home / End move focus without selecting; Enter / Space activate through native clicks. Disabled items are skipped. Button-aligned sm32 / md40 / lg48 sizes use existing tokens, quiet selected background and primary text without a selected ring, shared focus shadow, and the shared coarse-pointer 44px TouchTarget with reserved neighbor space. The Tier A keyboard contract lives on `/components/toggle-group`; Switch retains radio semantics and Tabs retains panel semantics.
 ## Checkbox task completion circle
@@ -113,7 +113,7 @@ Native buttons expose `aria-pressed` within `role="group"`. Roving tabindex and
 - Documentation: `src/pages/CheckboxPage.tsx`, `CheckboxCircleDemo.tsx`, `src/styles/checkbox-circle-specimen.css`; circle completion is restricted to tasks/checklists and row completion treatment stays consumer-owned.
 - Verification: `scripts/check-checkbox-circle-contract.test.mjs`, `scripts/fixtures/checkbox-circle-api-consumer.tsx`, `scripts/lib/checkbox-circle-contrast.mjs`, `scripts/lib/check-checkbox-circle-browser.mjs`. Package gate covers API/default/native markup/readonly semantics/token existence and both-theme contrast; browser gate covers native toggles, focus without preview, readonly, tone fill, reduced motion and coarse hit targets.
 ## Chat messages
-Bubble is separate from Message: chat has optional identity and direction, while Message retains its required author, comment attachments and receipt API unchanged. MessageScroller is separate from Scroller: keyed prepend anchors and message following need ownership of the viewport; the general Scroller API remains unchanged. The shadcn chat reference supplies conversation intent only; quiet chat surfaces map to existing q1travel panel/selected backgrounds, borders, spacing, radii and Button. No reference CSS, motion background or private tokens are shipped.
+Bubble is separate from Message: chat has optional identity and direction, while Message retains its required author, comment attachments and receipt API unchanged. MessageScroller is separate from Scroller: keyed prepend anchors and message following need ownership of the viewport; the general Scroller API remains unchanged. Quiet chat surfaces use existing q1travel panel/selected backgrounds, borders, spacing, radii and Button. No reference CSS, motion background or private tokens are shipped.
 The consumer mapping was checked against downstream chat-style implementations (read-only, no downstream edits).
 | Web capability | Package support / caller boundary |
 | --- | --- |

package/contracts/interface-guidelines.md

@@ -26,7 +26,7 @@ Adding a clause therefore means answering two questions before the wording: who
 - [both] MUST keep mobile control targets at least 44px where touch is expected.
 - [both] MUST use `--q1-touch-target-min` (44px) for the shared centered invisible child-span hit region of Button (all sizes, including compact consumer overrides and icon-only), CopyButton, Menu/DotsMenu triggers, Description info/hint buttons, and the independent FilterChip picker/clear buttons only under `(pointer: coarse), (any-pointer: coarse)`. Preserve every existing coarse-pointer visual-size rule. Only axes still below the minimum receive extra hit area; existing 44px targets do not expand outside their visual frame. The region covers the complete border box: canonical Button/CopyButton/Menu/DotsMenu borders are 1px, while Description borders are none. Consumers overriding a control border width must also set its private `--touch-target-border-width` to the actual per-side width (including zero for `border: none`); asymmetric borders need their own hit-region sizing. FilterChip keeps its default sm32 visual height and existing gaps/margins; its picker and clear hit regions must not overlap. Menu item rows use a real `min-height: var(--q1-touch-target-min)` under the same coarse-pointer query so neighboring rows remain independent. Focus rings stay on the visual control; child hit-region events activate that native control without replacing its pseudo-elements or overflow rules.
 - [both] MUST leave enough space for expanded targets: dense neighbors must not overlap each other's visual frames. Consumers must reserve the expansion on each side and avoid clipping ancestors; if this is impossible, regroup controls or use larger visual controls. The shared region cannot infer neighbor gaps or escape control/ancestor clipping; clipped compact controls must use a visual size of at least 44px.
-- [both] SHOULD NOT ship dense measured 24–32px controls to coarse pointers without enlargement: Apple HIG's 44pt guidance and WCAG 2.5.5 motivate q1travel's 44×44 CSS-pixel mobile usability target; pt and CSS pixels are different units.
+- [both] SHOULD NOT ship dense measured 24–32px controls to coarse pointers without enlargement: q1travel uses a 44×44 CSS-pixel mobile usability target, informed by WCAG 2.5.5.
 - [both] NEVER disable browser zoom.
 - [both] MUST avoid dead zones: if a region looks clickable, the clickable element must cover it.
 - [both] MUST show a loading indicator on in-flight buttons while keeping the original label.
@@ -191,7 +191,7 @@ Theming owns tokens and `color-scheme`; the interaction-contrast rule lives in D
 - [both] MUST separate Chinese characters from adjacent Latin letters or digits with a half-width space in authored prose; code contents, URLs, literal UI quotations, and code samples are excluded.
 - [both] MUST use full-width `，。：；` immediately after Chinese characters in authored Chinese sentences; code contents, URLs, literal UI quotations, and code samples are excluded.
 - [both] SHOULD use full-width `，。：；` throughout Chinese sentences, including after Latin words or inline code; identifying sentence language across mixed JSX nodes remains an editorial review item.
-- [both] SHOULD follow common Chinese technical-writing practice for mixed-language wording; Microsoft's Chinese localization guidance is a reference example, not a proprietary q1travel rule. Semantic choices and text whose rendered role cannot be reliably inferred remain editorial review items rather than machine-enforced requirements.
+- [both] SHOULD follow common Chinese technical-writing practice for mixed-language wording. Semantic choices and text whose rendered role cannot be reliably inferred remain editorial review items rather than machine-enforced requirements.
 - [both] SHOULD prefer short action-oriented labels.
 - [both] MUST use active voice.
 - [both] MUST use unambiguous action labels (「保存 API Key」, not 「继续」).
@@ -213,7 +213,7 @@ These copy clauses keep reader address and empty states consistent with a formal
 
 ### Component Naming
 
-- [repo] SHOULD use the industry-common component name when one exists, preferring shadcn/ui, then Radix. Invent a name only when neither has one. Name what the component is, not how it is built.
+- [repo] SHOULD use the industry-common component name when one exists. Invent a name only when no established name fits. Name what the component is, not how it is built.
 - [repo] MUST switch public names directly to the new export without deprecated aliases or old documentation route redirects; record the removal as a breaking change in CHANGELOG.
 
 ### Component Documentation Pages

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

@@ -1578,7 +1578,7 @@ export declare type MultiSelectProps = {
     preserveSelectionOrder?: boolean;
 };
 
-export declare function Navigation({ className, orientation, ...props }: NavigationProps): JSX.Element;
+export declare function Navigation({ className, orientation, variant, ...props }: NavigationProps): JSX.Element;
 
 export declare function NavigationGroup({ label, icon, expanded, defaultExpanded, onExpandedChange, children, }: NavigationGroupProps): JSX.Element;
 
@@ -1617,6 +1617,8 @@ export declare type NavigationItemProps = NavigationItemAsLink | NavigationItemA
 export declare type NavigationProps = HTMLAttributes<HTMLElement> & {
     'aria-label': string;
     orientation?: 'vertical' | 'horizontal';
+    /** Line styling applies only to horizontal navigation; vertical navigation ignores it. */
+    variant?: 'default' | 'line';
 };
 
 export declare function NavigationSection({ label, action, children, className, ...props }: NavigationSectionProps): JSX.Element;
@@ -2536,10 +2538,12 @@ export declare type ToolbarProps = {
     className?: string;
 };
 
-export declare function Tooltip({ content, placement, delay, triggerLabel, children, align, tip, center, }: {
+export declare function Tooltip({ content, placement, delay, disabled, triggerLabel, children, align, tip, center, }: {
     content: ReactNode;
     placement?: TooltipPlacement;
     delay?: number;
+    /** 禁用提示而保留触发器；关闭已显示或待显示的提示，不影响按钮自身的可操作性。 */
+    disabled?: boolean;
     /** 内部默认触发器的文案；传 children 时不使用。 */
     triggerLabel?: string;
     /** 自定义触发器：包裹任意单个元素/组件（Button、原生 a/span 等）代替内部默认按钮。 */