@q1travel/design-system 0.30.4 → 0.30.6

package/contracts/design.dark.md

@@ -525,13 +525,16 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 
 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.
+- 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.
-- 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.
+- 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.
 - Skeleton holds the shape of content that is coming. Spinner and LoadingDots say only that something is happening.

package/contracts/design.md

@@ -525,13 +525,16 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 
 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.
+- 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.
-- 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.
+- 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.
 - Skeleton holds the shape of content that is coming. Spinner and LoadingDots say only that something is happening.

package/contracts/implementation-map.md

@@ -138,6 +138,6 @@ Accepted 2026-10-08: explicitly sized single-line Button, ButtonLink, Input, Sea
 
 ## RegionErrorState retry and announcement boundary
 
-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`). There is no `size` prop; the two layouts cover the observed hosts.
+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.

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 = {
@@ -1260,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 = {
@@ -2068,14 +2090,14 @@ export declare type RangeValue = {
 
 export declare function RegionErrorState({ title, description, layout, headingLevel, onRetry, retrying, live, }: RegionErrorStateProps): JSX.Element;
 
-export declare type RegionErrorStateLayout = 'center' | 'inline';
+export declare type RegionErrorStateLayout = 'center' | 'inline' | 'strip';
 
 export declare type RegionErrorStateProps = {
     /** 失败的是哪块内容，点名资源；必填。 */
     title: string;
     /** 原因或下一步，一句话；可省略。 */
     description?: string;
-    /** center：居中占位，用于表格主体与大区块；inline：左对齐紧凑行，用于卡片与页面分区。默认 center。 */
+    /** center：居中占位，用于表格主体与大区块；inline：左对齐紧凑行，用于卡片与页面分区。strip：整宽中性底条，用于列表位与「加载更多」行，重试始终在条内右侧。默认 center。 */
     layout?: RegionErrorStateLayout;
     /** 标题层级：缺省渲染 p（不进标题树）；作为页面区块时传 2-6 渲染对应 h 标签。 */
     headingLevel?: 2 | 3 | 4 | 5 | 6;