@q1travel/design-system 0.30.6 → 0.30.7

package/contracts/design.dark.md

@@ -528,12 +528,11 @@ CheckCircleFill accepts `tone?: 'default' | 'success'` (default `default`); succ
 
 **Images and proportions.** AspectRatio requires a finite positive width/height ratio (invalid values render as 1 with one development warning) and only reserves layout space. Image requires alt (empty for decoration), defaults to contain and eager, accepts optional src, fit, loading, sm/md/lg square sizes (32/40/48), onError and root className; omitted size follows host width and natural image ratio. Loading keeps img mounted under a decorative Skeleton; missing and failed sources show a single named image fallback, and source changes isolate stale events. Decorative states are hidden from assistive technology; neither Image nor its host becomes inert. Inside AspectRatio, omit size: the Image root and img fill the ratio frame and object-fit controls complete centered containment or cropping. No new tokens or existing-consumer migration; remove new usages before reverting the additive exports.
 
-**Status and feedback.** Banner, ProjectBanner, Note, ErrorCard, RegionErrorState, ErrorMessage, EmptyState, Badge, Pill, CheckCircleFill, StatusDot, ToastProvider, useToast, Feedback, PageFeedback, Spinner, LoadingDots, Skeleton.
 **Status and feedback.** Banner, ProjectBanner, Note, ErrorCard, RegionErrorState, ErrorMessage, EmptyState, Badge, Pill, CheckCircleFill, StatusDot, ToastProvider, useToast, Feedback, PageFeedback, Spinner, LoadingDots, Skeleton, StatusPage, SkeletonIllustration, EmptyListIllustration.
 
 - Banner announces at page scope. Note is an inline aside. ErrorMessage sits against one field. ErrorCard replaces a region that failed to load. Picking the widest one available overstates the problem.
 - RegionErrorState replaces only the failed region in place (table body under a kept header, card body, page section) while the rest of the page stays usable: neutral surface, danger color on the icon only, polite `role=status` by default, built-in retry that keeps focus while `retrying`. ErrorCard is for a failure that blocks the current task (danger card, assertive `role=alert`). EmptyState is a successful load with no data: default `layout="center"` keeps the full empty view; `layout="inline"` is an icon and regular secondary title row inside a section whose heading and actions belong to the host, without description, actions, headingLevel, or illustration. Center accepts a decorative `illustration?: ReactNode` in place of icon; built-in `EmptyListIllustration` depicts a fully processed list or inbox, without an icon backplate. `layout="strip"` adds a full-width neutral strip for list failures and load-more rows, with retry always inside its right edge. See `implementation-map.md` for the retry and announcement boundary.
-- StatusPage defaults to a whole unavailable page with a caller-owned title, decorative SkeletonIllustration, plain-text description rendered as a paragraph, and actions. Its size="region" variant centers an icon or small illustration, title, description, and up to two actions inside a substantial content region, with a transparent background and content-driven height. ErrorCard covers a blocking compact failure; RegionErrorState is a compact retryable region message with its own status announcement; EmptyState means loading succeeded without content. StatusPage creates no live region; its host owns focus and announcements. StatusPage code is metadata only, never a message or spoken number.
+- StatusPage defaults to a whole unavailable page with a caller-owned title, decorative SkeletonIllustration, plain-text description rendered as a paragraph, and actions. Its size="region" variant centers an icon or small illustration, title, description, and up to two actions inside a substantial content region, with a transparent background and content-driven height. ErrorCard covers a blocking compact failure; RegionErrorState is a compact retryable region message with its own status announcement; EmptyState means loading succeeded without content. StatusPage headingLevel accepts 1–6 (default 1); choose the next heading level under the host section. Existing omitted, 1 and 2 calls need no migration. StatusPage creates no live region; its host owns focus and announcements. StatusPage code is metadata only, never a message or spoken number.
 - RegionErrorState replaces only the failed region in place (table body under a kept header, card body, page section) while the rest of the page stays usable: neutral surface, danger color on the icon only, polite `role=status` by default, built-in retry that keeps focus while `retrying`. ErrorCard is for a failure that blocks the current task (danger card, assertive `role=alert`). EmptyState is a successful load with no data. `layout="strip"` adds a full-width neutral strip for list failures and load-more rows, with retry always inside its right edge. See `implementation-map.md` for the retry and announcement boundary.
 - Toast is for non-blocking confirmation of something that already happened. It is not where an error the reader must act on belongs.
 - Badge and Pill label a state drawn from a known set. Ordinary metadata is text, not a badge. StatusDot is the smallest form, and needs a text label beside it.

package/contracts/design.md

@@ -528,12 +528,11 @@ CheckCircleFill accepts `tone?: 'default' | 'success'` (default `default`); succ
 
 **Images and proportions.** AspectRatio requires a finite positive width/height ratio (invalid values render as 1 with one development warning) and only reserves layout space. Image requires alt (empty for decoration), defaults to contain and eager, accepts optional src, fit, loading, sm/md/lg square sizes (32/40/48), onError and root className; omitted size follows host width and natural image ratio. Loading keeps img mounted under a decorative Skeleton; missing and failed sources show a single named image fallback, and source changes isolate stale events. Decorative states are hidden from assistive technology; neither Image nor its host becomes inert. Inside AspectRatio, omit size: the Image root and img fill the ratio frame and object-fit controls complete centered containment or cropping. No new tokens or existing-consumer migration; remove new usages before reverting the additive exports.
 
-**Status and feedback.** Banner, ProjectBanner, Note, ErrorCard, RegionErrorState, ErrorMessage, EmptyState, Badge, Pill, CheckCircleFill, StatusDot, ToastProvider, useToast, Feedback, PageFeedback, Spinner, LoadingDots, Skeleton.
 **Status and feedback.** Banner, ProjectBanner, Note, ErrorCard, RegionErrorState, ErrorMessage, EmptyState, Badge, Pill, CheckCircleFill, StatusDot, ToastProvider, useToast, Feedback, PageFeedback, Spinner, LoadingDots, Skeleton, StatusPage, SkeletonIllustration, EmptyListIllustration.
 
 - Banner announces at page scope. Note is an inline aside. ErrorMessage sits against one field. ErrorCard replaces a region that failed to load. Picking the widest one available overstates the problem.
 - RegionErrorState replaces only the failed region in place (table body under a kept header, card body, page section) while the rest of the page stays usable: neutral surface, danger color on the icon only, polite `role=status` by default, built-in retry that keeps focus while `retrying`. ErrorCard is for a failure that blocks the current task (danger card, assertive `role=alert`). EmptyState is a successful load with no data: default `layout="center"` keeps the full empty view; `layout="inline"` is an icon and regular secondary title row inside a section whose heading and actions belong to the host, without description, actions, headingLevel, or illustration. Center accepts a decorative `illustration?: ReactNode` in place of icon; built-in `EmptyListIllustration` depicts a fully processed list or inbox, without an icon backplate. `layout="strip"` adds a full-width neutral strip for list failures and load-more rows, with retry always inside its right edge. See `implementation-map.md` for the retry and announcement boundary.
-- StatusPage defaults to a whole unavailable page with a caller-owned title, decorative SkeletonIllustration, plain-text description rendered as a paragraph, and actions. Its size="region" variant centers an icon or small illustration, title, description, and up to two actions inside a substantial content region, with a transparent background and content-driven height. ErrorCard covers a blocking compact failure; RegionErrorState is a compact retryable region message with its own status announcement; EmptyState means loading succeeded without content. StatusPage creates no live region; its host owns focus and announcements. StatusPage code is metadata only, never a message or spoken number.
+- StatusPage defaults to a whole unavailable page with a caller-owned title, decorative SkeletonIllustration, plain-text description rendered as a paragraph, and actions. Its size="region" variant centers an icon or small illustration, title, description, and up to two actions inside a substantial content region, with a transparent background and content-driven height. ErrorCard covers a blocking compact failure; RegionErrorState is a compact retryable region message with its own status announcement; EmptyState means loading succeeded without content. StatusPage headingLevel accepts 1–6 (default 1); choose the next heading level under the host section. Existing omitted, 1 and 2 calls need no migration. StatusPage creates no live region; its host owns focus and announcements. StatusPage code is metadata only, never a message or spoken number.
 - RegionErrorState replaces only the failed region in place (table body under a kept header, card body, page section) while the rest of the page stays usable: neutral surface, danger color on the icon only, polite `role=status` by default, built-in retry that keeps focus while `retrying`. ErrorCard is for a failure that blocks the current task (danger card, assertive `role=alert`). EmptyState is a successful load with no data. `layout="strip"` adds a full-width neutral strip for list failures and load-more rows, with retry always inside its right edge. See `implementation-map.md` for the retry and announcement boundary.
 - Toast is for non-blocking confirmation of something that already happened. It is not where an error the reader must act on belongs.
 - Badge and Pill label a state drawn from a known set. Ordinary metadata is text, not a badge. StatusDot is the smallest form, and needs a text label beside it.

package/contracts/implementation-map.md

@@ -37,6 +37,10 @@ README owns the repository inventory and generated-file boundary. This file owns
 - The public documentation navigation groups are `基础`, `品牌`, and `组件`. Product compositions are owned by downstream consumers.
 - If a capability is missing from a shared component, add the capability to that component before adding another page-local pattern.
 
+## Breadcrumb Route Links — Accepted 2026-10-25 (#563)
+
+Breadcrumb and CollapsibleBreadcrumb accept an optional `linkComponent` for single-page routing. It replaces only items with a destination that are neither current nor disabled; static items and the collapse button keep their native behavior. Collapsible endpoints, middle levels and short paths use the same adapter. The adapter must render exactly one native `a` root and forward all received anchor properties, including `ref`, `className` and `children`. `LinkComponentProps` keeps a required string `href`. Omitting the adapter preserves native anchors, markup, classes, attributes, focus order and appearance. Consumers opt in per component; existing calls need no migration. Roll back by removing the optional prop before reverting the addition.
+
 ## Documentation Section Ownership
 
 Two component-page sections are q1travel supersets with no external counterpart, so their scope is defined here rather than inferred page by page.

package/contracts/interface-guidelines.md

@@ -211,6 +211,10 @@ Theming owns tokens and `color-scheme`; the interaction-contrast rule lives in D
 
 These copy clauses keep reader address and empty states consistent with a formal business console: address the reader as 「您」, omit trailing punctuation from empty-state titles, and explain when content will appear in the description.
 
+### Second-Line Text
+
+- [both] SHOULD keep second-line text in options and list rows — option descriptions, row subtitles, and secondary labels — empty unless it adds information nothing else provides. Add it only when it carries information the label cannot: items at the same level share the same or easily confused labels and the primary text cannot explain itself, or choosing the item has a result the user cannot see from the label, such as ordering, scope, reach, or timing. Translations, restatements of the label, and decorative notes are not information. The pull request must give the reason. Treat second-line text as an exception patch for the primary message, not as standard layout. Severe consequences such as high-risk, irreversible, or data-overwriting actions are stated in the DestructiveActionModal confirmation, not in option or row second lines. When an external product is used as a reference, its second-line information is not carried over. Body descriptions of panels such as empty states, error states, and dialogs are the main message and are not second-line text; field helper text follows the existing note and tooltip rules.
+
 ### Component Naming
 
 - [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.

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

@@ -202,10 +202,12 @@ export declare type BookProps = {
     width?: number | string;
 } & Omit<HTMLAttributes<HTMLDivElement>, 'children'>;
 
-export declare function Breadcrumb({ items, label, type, }: {
+export declare function Breadcrumb({ items, label, type, linkComponent, }: {
     items: BreadcrumbCrumb[];
     label: string;
     type?: 'text' | 'menu';
+    /** 用于单页应用内路由跳转；省略时渲染原生 a */
+    linkComponent?: LinkComponent;
 }): JSX.Element;
 
 export declare type BreadcrumbCrumb = {
@@ -586,9 +588,11 @@ export declare function CollapseGroup({ multiple, children }: {
     children: ReactNode;
 }): JSX.Element;
 
-export declare function CollapsibleBreadcrumb({ items, label }: {
+export declare function CollapsibleBreadcrumb({ items, label, linkComponent }: {
     items: BreadcrumbCrumb[];
     label: string;
+    /** 用于单页应用内路由跳转；省略时渲染原生 a */
+    linkComponent?: LinkComponent;
 }): 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;
@@ -1410,6 +1414,13 @@ export declare function Label({ htmlFor, required, hint, children, }: {
 
 export declare function Link({ href, tone, external, className, children, ref, ...rest }: LinkProps): JSX.Element;
 
+export declare type LinkComponent = (props: LinkComponentProps) => ReactElement | null;
+
+/** 注入的链接组件收到的属性：原生 a 属性 + 必填字符串 href；实现必须渲染且只渲染一个原生 a，并透传全部属性（含 ref、className、children）。 */
+export declare type LinkComponentProps = Omit<ComponentPropsWithRef<'a'>, 'href'> & {
+    href: string;
+};
+
 export declare type LinkProps = {
     /** 目标地址。省略时渲染为静态文本，不表示 disabled 链接。 */
     href?: string;
@@ -2445,7 +2456,7 @@ export declare type StatusPageProps = {
     secondaryAction?: ReactNode;
     illustration?: ReactNode;
     icon?: ReactNode;
-    headingLevel?: 1 | 2;
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
 };
 
 export declare function Switch({ options, ariaLabel, name, defaultValue, value, onChange, size, variant, fullWidth, iconOnly, }: {