@q1travel/design-system 0.30.3 → 0.30.5

package/contracts/design.dark.md

@@ -501,7 +501,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.
-- Switch selects among mutually exclusive views or modes; its outer sm / md / lg heights are 32 / 40 / 48px on fine pointers, defaulting to md.
+- 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.
 
@@ -512,7 +512,7 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 - HoverCard presents supplemental noninteractive content on fine-pointer hover or keyboard focus after openDelay (default 0ms); closeDelay defaults to 90ms and entering the card cancels closing. Escape dismisses without moving focus into the card; aria-describedby connects the named native trigger to a nonmodal tooltip. Coarse/touch hover is ignored, trigger activation is preserved, and reduced-motion uses the shared Popover styles and anchored overlay foundation.
 - Popover is a named anchored dialog for interactive content; it supports controlled/default open, four-side collision positioning plus controlled anchorRef placement, menu/listbox role focus, width matching, Escape focus return and outside pointer-down dismissal. Keyboard opening moves focus into content; pointer opening retains trigger focus and Tab enters the panel. It is nonmodal by default; opt-in modal locks the background and traps focus. ensurePopoverRoot exposes the same shared Foundation host for consumer-owned sibling portals; dismissExcludeRefs and nested panels preserve parent dismissal boundaries.
 - Modal blocks and demands an answer. Use it for confirmation, not for a long form; a long form belongs in a Drawer or its own route.
-- DestructiveActionModal is the required shape for irreversible actions. Do not rebuild that confirmation from a plain Modal.
+- DestructiveActionModal is the required shape for irreversible actions. Do not rebuild that confirmation from a plain Modal. It is also where high-risk, irreversible, or data-overwriting consequences are stated; do not move that warning into option second lines.
 - Sheet slides in from an edge with a focus trap; opt-in `mobileFullscreen` fills narrow viewports with safe-area padding and no outer inset or radius, while default floating spacing remains unchanged; Drawer is the wider panel form. Menu is anchored and flips on collision; ContextMenu and DotsMenu share its keyboard engine.
 - Tooltip carries a short label for a control. Anything a reader must read to decide belongs in the page or in a ContextCard.
 
@@ -523,9 +523,17 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 - Gauge is one ratio as a ring. Progress is advancement along a task, and takes segment stops.
 - RelativeTimeCard reveals the absolute time behind a relative one. Prefer it to printing both.
 
+CheckCircleFill accepts `tone?: 'default' | 'success'` (default `default`); success adds `.check-circle-fill--success`, using the same derived solid success fill as Badge and `--q1-color-action-on-primary` foreground; existing calls retain their DOM and appearance, and adjacent text conveys completion.
+
+
+**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. 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.
 - 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. 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.
@@ -604,6 +612,8 @@ Label, value, and detail spacing is identical across every peer in a set. One pa
 
 **Copy.** Sentence case headings that state the claim rather than name the section. Simplify the language, never the claim. Keep every qualifier attached to the number it qualifies.
 
+Second-line text in options and list rows — option descriptions, row subtitles, and secondary labels — stays 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.
+
 ## DO
 
 - Answer the reader's question in the first viewport, together with the one relationship the page turns on.

package/contracts/design.md

@@ -501,7 +501,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.
-- Switch selects among mutually exclusive views or modes; its outer sm / md / lg heights are 32 / 40 / 48px on fine pointers, defaulting to md.
+- 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.
 
@@ -512,7 +512,7 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 - HoverCard presents supplemental noninteractive content on fine-pointer hover or keyboard focus after openDelay (default 0ms); closeDelay defaults to 90ms and entering the card cancels closing. Escape dismisses without moving focus into the card; aria-describedby connects the named native trigger to a nonmodal tooltip. Coarse/touch hover is ignored, trigger activation is preserved, and reduced-motion uses the shared Popover styles and anchored overlay foundation.
 - Popover is a named anchored dialog for interactive content; it supports controlled/default open, four-side collision positioning plus controlled anchorRef placement, menu/listbox role focus, width matching, Escape focus return and outside pointer-down dismissal. Keyboard opening moves focus into content; pointer opening retains trigger focus and Tab enters the panel. It is nonmodal by default; opt-in modal locks the background and traps focus. ensurePopoverRoot exposes the same shared Foundation host for consumer-owned sibling portals; dismissExcludeRefs and nested panels preserve parent dismissal boundaries.
 - Modal blocks and demands an answer. Use it for confirmation, not for a long form; a long form belongs in a Drawer or its own route.
-- DestructiveActionModal is the required shape for irreversible actions. Do not rebuild that confirmation from a plain Modal.
+- DestructiveActionModal is the required shape for irreversible actions. Do not rebuild that confirmation from a plain Modal. It is also where high-risk, irreversible, or data-overwriting consequences are stated; do not move that warning into option second lines.
 - Sheet slides in from an edge with a focus trap; opt-in `mobileFullscreen` fills narrow viewports with safe-area padding and no outer inset or radius, while default floating spacing remains unchanged; Drawer is the wider panel form. Menu is anchored and flips on collision; ContextMenu and DotsMenu share its keyboard engine. DotsMenu accepts contextual `label` (default 更多操作) for trigger and menu, plus `{type:'separator'}` entries using the shared Menu separator; roving focus and typeahead skip separators and disabled items.
 - Tooltip carries a short label for a control. Anything a reader must read to decide belongs in the page or in a ContextCard.
 
@@ -523,9 +523,17 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 - Gauge is one ratio as a ring. Progress is advancement along a task, and takes segment stops.
 - RelativeTimeCard reveals the absolute time behind a relative one. Prefer it to printing both.
 
+CheckCircleFill accepts `tone?: 'default' | 'success'` (default `default`); success adds `.check-circle-fill--success`, using the same derived solid success fill as Badge and `--q1-color-action-on-primary` foreground; existing calls retain their DOM and appearance, and adjacent text conveys completion.
+
+
+**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. 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.
 - 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. 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.
@@ -604,6 +612,8 @@ Label, value, and detail spacing is identical across every peer in a set. One pa
 
 **Copy.** Sentence case headings that state the claim rather than name the section. Simplify the language, never the claim. Keep every qualifier attached to the number it qualifies.
 
+Second-line text in options and list rows — option descriptions, row subtitles, and secondary labels — stays 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.
+
 ## DO
 
 - Answer the reader's question in the first viewport, together with the one relationship the page turns on.

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

@@ -18,6 +18,7 @@ import { MouseEvent as MouseEvent_2 } from 'react';
 import { MouseEventHandler } from 'react';
 import { PointerEventHandler } from 'react';
 import { ReactElement } from 'react';
+import { ReactEventHandler } from 'react';
 import { ReactNode } from 'react';
 import { Ref } from 'react';
 import { RefAttributes } from 'react';
@@ -29,6 +30,14 @@ import { TextareaHTMLAttributes } from 'react';
 
 export declare function addDays(date: Date, amount: number): Date;
 
+export declare function AspectRatio({ ratio, children, className }: AspectRatioProps): JSX.Element;
+
+export declare type AspectRatioProps = {
+    ratio: number;
+    children: ReactNode;
+    className?: string;
+};
+
 export declare function Attachment({ name, size, type, progress, error, onRetry, onRemove, }: AttachmentProps): JSX.Element;
 
 export declare type AttachmentProps = {
@@ -465,10 +474,11 @@ export declare type CheckboxProps = ControlOptionOwnProps & (FieldShellProps | F
 } & Omit<ControlOptionNativeInputProps, 'size'>;
 
 /** 装饰性圆底勾；当前或选中语义由宿主表达。 */
-export declare function CheckCircleFill({ className, ...props }: CheckCircleFillProps): JSX.Element;
+export declare function CheckCircleFill({ className, tone, ...props }: CheckCircleFillProps): JSX.Element;
 
 export declare type CheckCircleFillProps = {
     className?: string;
+    tone?: 'default' | 'success';
     children?: never;
     [attribute: `data-${string}`]: string | number | boolean | undefined;
 };
@@ -998,15 +1008,27 @@ export declare function Drawer({ open, onClose, title, children, footer, height,
     height?: number;
 }): ReactNode;
 
-export declare function EmptyState({ icon, title, description, actions, headingLevel, }: {
+/** 列表或收件箱内容已全部处理的装饰插画；状态含义由相邻文字表达。 */
+export declare function EmptyListIllustration(): JSX.Element;
+
+export declare function EmptyState({ icon, illustration, title, description, actions, headingLevel, layout, }: {
     icon?: ReactNode;
     title: string;
+} & ({
+    layout?: 'center';
+    illustration?: ReactNode;
     description?: string;
     /** CTA 区：传家族 <Button> 与次要链接；最多一个主 CTA。 */
     actions?: ReactNode;
     /** 标题层级：缺省渲染 p（不进标题树）；作为页面区块时传 2-6 渲染对应 h 标签。 */
     headingLevel?: 2 | 3 | 4 | 5 | 6;
-}): JSX.Element;
+} | {
+    layout: 'inline';
+    illustration?: never;
+    description?: never;
+    actions?: never;
+    headingLevel?: never;
+})): JSX.Element;
 
 /** Public host for consumer-owned sibling portals. Package overlays share this Foundation root. */
 export declare function ensurePopoverRoot(): HTMLElement | null;
@@ -1247,6 +1269,19 @@ export declare type IconButtonProps = IconButtonAccessibleName & IconButtonBaseP
     ref?: Ref<HTMLButtonElement>;
 };
 
+declare function Image_2({ src, alt, loading, fit, size, onError, className }: ImageProps): JSX.Element;
+export { Image_2 as Image }
+
+export declare type ImageProps = {
+    src?: string;
+    alt: string;
+    loading?: 'eager' | 'lazy';
+    fit?: 'contain' | 'cover';
+    size?: 'sm' | 'md' | 'lg';
+    onError?: ReactEventHandler<HTMLImageElement>;
+    className?: string;
+};
+
 export declare function InfoTip({ label, content }: InfoTipProps): JSX.Element;
 
 export declare type InfoTipProps = {
@@ -2312,6 +2347,8 @@ declare type SkeletonDataAttributes = {
     [key: `data-${string}`]: string | number | boolean | null | undefined;
 };
 
+export declare function SkeletonIllustration(): JSX.Element;
+
 export declare type SkeletonProps = {
     shape?: SkeletonShape;
     animated?: boolean;
@@ -2395,7 +2432,23 @@ export declare function StatusDot({ tone, label, showLabel, titlePrefix, }: {
 
 export declare type StatusDotTone = 'neutral' | 'warning' | 'success' | 'danger';
 
-export declare function Switch({ options, ariaLabel, name, defaultValue, value, onChange, size, fullWidth, iconOnly, }: {
+export declare function StatusPage({ code, size, title, description, primaryAction, secondaryAction, illustration, icon, headingLevel }: StatusPageProps): JSX.Element;
+
+export declare type StatusPageCode = '402' | '403' | '404' | '500' | 'offline' | 'timeout' | 'session-expired';
+
+export declare type StatusPageProps = {
+    code?: StatusPageCode;
+    size?: 'page' | 'region';
+    title: string;
+    description?: string;
+    primaryAction?: ReactNode;
+    secondaryAction?: ReactNode;
+    illustration?: ReactNode;
+    icon?: ReactNode;
+    headingLevel?: 1 | 2;
+};
+
+export declare function Switch({ options, ariaLabel, name, defaultValue, value, onChange, size, variant, fullWidth, iconOnly, }: {
     options: SwitchOption[];
     ariaLabel: string;
     name?: string;
@@ -2403,6 +2456,7 @@ export declare function Switch({ options, ariaLabel, name, defaultValue, value,
     value?: string;
     onChange?: (value: string) => void;
     size?: 'sm' | 'md' | 'lg';
+    variant?: 'segmented' | 'cards';
     fullWidth?: boolean;
     /** 纯图标模式：文字标签仍在，只是视觉隐藏（q1-sr-only），可访问名称不丢失。 */
     iconOnly?: boolean;