@q1travel/design-system 0.31.1 → 0.31.2

package/contracts/design.dark.md

@@ -540,8 +540,8 @@ CheckCircleFill accepts `tone?: 'default' | 'success'` (default `default`); succ
 
 **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 a small illustration or icon and regular secondary title row inside a section whose heading and actions belong to the host, without description, actions, or headingLevel. Inline accepts `illustration?: ReactNode`, using `--q1-space-16` (64px) for its width and preserving the artwork aspect ratio; illustration takes priority over icon with a development warning when both are supplied. Without illustration, existing icon-only and title-only calls stay unchanged. Center accepts a decorative `illustration?: ReactNode` in place of icon; when neither illustration nor icon is supplied, it renders `EmptyListIllustration variant="neutral"` inside the decorative `empty-state__illustration` slot. Explicit icons retain their slot with a transparent background in both themes. Both layouts accept `titleHidden?: boolean`: true adds `empty-state--title-hidden` to the existing root and `q1-sr-only` to the required title, preserving its p or h2–h6 tag, text and accessibility semantics. Center keeps illustration/icon, optional description and actions; inline keeps its small illustration or icon. The hidden title takes no layout space; remaining siblings keep the existing gap and margins, and an illustration/icon alone has no trailing margin. Omitted or false preserves the existing DOM, classes and styles exactly. Built-in `EmptyListIllustration` accepts `scene?: 'list' | 'search' | 'complete' | 'chart' | 'inventory' | 'orders' | 'product' | 'permission'` and the compatible `variant?: 'complete' | 'neutral'`. Explicit scene takes priority; without scene, neutral maps to list and all other calls default to complete. Accepted #830 intentionally changes both standalone default complete and EmptyState default list artwork and internal SVG structure; the outer decorative span, class and 96×104 viewBox remain. Complete draws its own decorative check without depending on CheckCircleFill. All scenes use opaque neutral bodies, token radii, canonical stroke width, and at most one brand-colored element (light primary-700, dark primary-900); geometry is identical across themes. Body contrast against the actual panel is at least 1.3:1. Both variants have no 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.
+- Banner accepts a string `title` and paragraph-inline `children` (text and inline Link, no block elements). `action: BannerAction` is either `{ label, href }` or `{ label, onClick, loading?, disabled? }`, mutually exclusive. The exported `BannerAction` derives button events and states from ButtonProps. Buttons use `type="button"`, size sm, rounded, primary for announcements and secondary for tone strips, with layout class `banner__button-action`. Loading retains focus with aria-disabled and blocks activation; disabled takes priority and leaves the Tab order. Loading adds no aria-busy; Banner adds no role or live region. Progress ignores either action. Existing links and calls omitting new capabilities retain their complete markup; no existing consumer migration is required. Remove button calls and BannerAction imports before reverting this addition. 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 a small illustration or icon and regular secondary title row inside a section whose heading and actions belong to the host, without description, actions, or headingLevel. Inline accepts `illustration?: ReactNode`, using `--q1-space-16` (64px) for its width and preserving the artwork aspect ratio; illustration takes priority over icon with a development warning when both are supplied. Without illustration, existing icon-only and title-only calls stay unchanged. Center accepts a decorative `illustration?: ReactNode` in place of icon; when neither illustration nor icon is supplied, it renders `EmptyListIllustration variant="neutral"` inside the decorative `empty-state__illustration` slot. Explicit icons retain their slot with a transparent background in both themes. Both layouts accept `titleHidden?: boolean`: true adds `empty-state--title-hidden` to the existing root and `q1-sr-only` to the required title, preserving its p or h2–h6 tag, text and accessibility semantics. Center keeps illustration/icon, optional description and actions; inline keeps its small illustration or icon. The hidden title takes no layout space; remaining siblings keep the existing gap and margins, and an illustration/icon alone has no trailing margin. Omitted or false preserves the existing DOM, classes and styles exactly. Built-in `EmptyListIllustration` accepts `scene?: 'list' | 'search' | 'complete' | 'chart' | 'inventory' | 'orders' | 'product' | 'permission' | 'purchase' | 'supplier' | 'team' | 'notification' | 'store' | 'task' | 'session' | 'activity'` and the compatible `variant?: 'complete' | 'neutral'`. Explicit scene takes priority; without scene, neutral maps to list and all other calls default to complete. Accepted #830 intentionally changes both standalone default complete and EmptyState default list artwork and internal SVG structure; the outer decorative span, class and 96×104 viewBox remain. Complete draws its own decorative check without depending on CheckCircleFill. All scenes use opaque neutral bodies, token radii, canonical stroke width, and exactly one brand-colored element (light primary-700, dark primary-900); geometry is identical across themes. Body contrast against the actual panel is at least 1.3:1. Both variants have no 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 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.

package/contracts/design.md

@@ -540,8 +540,8 @@ CheckCircleFill accepts `tone?: 'default' | 'success'` (default `default`); succ
 
 **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 a small illustration or icon and regular secondary title row inside a section whose heading and actions belong to the host, without description, actions, or headingLevel. Inline accepts `illustration?: ReactNode`, using `--q1-space-16` (64px) for its width and preserving the artwork aspect ratio; illustration takes priority over icon with a development warning when both are supplied. Without illustration, existing icon-only and title-only calls stay unchanged. Center accepts a decorative `illustration?: ReactNode` in place of icon; when neither illustration nor icon is supplied, it renders `EmptyListIllustration variant="neutral"` inside the decorative `empty-state__illustration` slot. Explicit icons retain their slot with a transparent background in both themes. Both layouts accept `titleHidden?: boolean`: true adds `empty-state--title-hidden` to the existing root and `q1-sr-only` to the required title, preserving its p or h2–h6 tag, text and accessibility semantics. Center keeps illustration/icon, optional description and actions; inline keeps its small illustration or icon. The hidden title takes no layout space; remaining siblings keep the existing gap and margins, and an illustration/icon alone has no trailing margin. Omitted or false preserves the existing DOM, classes and styles exactly. Built-in `EmptyListIllustration` accepts `scene?: 'list' | 'search' | 'complete' | 'chart' | 'inventory' | 'orders' | 'product' | 'permission'` and the compatible `variant?: 'complete' | 'neutral'`. Explicit scene takes priority; without scene, neutral maps to list and all other calls default to complete. Accepted #830 intentionally changes both standalone default complete and EmptyState default list artwork and internal SVG structure; the outer decorative span, class and 96×104 viewBox remain. Complete draws its own decorative check without depending on CheckCircleFill. All scenes use opaque neutral bodies, token radii, canonical stroke width, and at most one brand-colored element (light primary-700, dark primary-900); geometry is identical across themes. Body contrast against the actual panel is at least 1.3:1. Both variants have no 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.
+- Banner accepts a string `title` and paragraph-inline `children` (text and inline Link, no block elements). `action: BannerAction` is either `{ label, href }` or `{ label, onClick, loading?, disabled? }`, mutually exclusive. The exported `BannerAction` derives button events and states from ButtonProps. Buttons use `type="button"`, size sm, rounded, primary for announcements and secondary for tone strips, with layout class `banner__button-action`. Loading retains focus with aria-disabled and blocks activation; disabled takes priority and leaves the Tab order. Loading adds no aria-busy; Banner adds no role or live region. Progress ignores either action. Existing links and calls omitting new capabilities retain their complete markup; no existing consumer migration is required. Remove button calls and BannerAction imports before reverting this addition. 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 a small illustration or icon and regular secondary title row inside a section whose heading and actions belong to the host, without description, actions, or headingLevel. Inline accepts `illustration?: ReactNode`, using `--q1-space-16` (64px) for its width and preserving the artwork aspect ratio; illustration takes priority over icon with a development warning when both are supplied. Without illustration, existing icon-only and title-only calls stay unchanged. Center accepts a decorative `illustration?: ReactNode` in place of icon; when neither illustration nor icon is supplied, it renders `EmptyListIllustration variant="neutral"` inside the decorative `empty-state__illustration` slot. Explicit icons retain their slot with a transparent background in both themes. Both layouts accept `titleHidden?: boolean`: true adds `empty-state--title-hidden` to the existing root and `q1-sr-only` to the required title, preserving its p or h2–h6 tag, text and accessibility semantics. Center keeps illustration/icon, optional description and actions; inline keeps its small illustration or icon. The hidden title takes no layout space; remaining siblings keep the existing gap and margins, and an illustration/icon alone has no trailing margin. Omitted or false preserves the existing DOM, classes and styles exactly. Built-in `EmptyListIllustration` accepts `scene?: 'list' | 'search' | 'complete' | 'chart' | 'inventory' | 'orders' | 'product' | 'permission' | 'purchase' | 'supplier' | 'team' | 'notification' | 'store' | 'task' | 'session' | 'activity'` and the compatible `variant?: 'complete' | 'neutral'`. Explicit scene takes priority; without scene, neutral maps to list and all other calls default to complete. Accepted #830 intentionally changes both standalone default complete and EmptyState default list artwork and internal SVG structure; the outer decorative span, class and 96×104 viewBox remain. Complete draws its own decorative check without depending on CheckCircleFill. All scenes use opaque neutral bodies, token radii, canonical stroke width, and exactly one brand-colored element (light primary-700, dark primary-900); geometry is identical across themes. Body contrast against the actual panel is at least 1.3:1. Both variants have no 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 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.

package/contracts/implementation-map.md

@@ -102,6 +102,11 @@ Click, ArrowLeft/ArrowRight, Home, and End notify activation; controlled selecti
 changes only when the parent updates `value`. Keyboard navigation follows the
 focused enabled tab while the parent update is pending, and a later value update
 does not pull focus from the activated button. Consumers own URL synchronization.
+Line disabled labels and their icons use `text-muted`, with at least 3:1 contrast
+against the background in both themes and less contrast than enabled labels. Hover
+and press do not strengthen disabled items. A selected-disabled style combination
+keeps a muted underline; unselected disabled items have no underline. Runtime
+selection still falls back to an enabled item as described above.
 
 ## Record activity (accepted 2026-10-06)
 

package/contracts/interface-guidelines.md

@@ -243,7 +243,7 @@ Component pages follow one skeleton so a reader who has used one page can find t
 
 ### Empty illustrations
 
-Accepted #830: decorative empty illustrations share a 96×104 viewBox, radius-3 outer frames, radius-1 clips, and ICON_STROKE_WIDTH round strokes. All scene geometry, including half the computed stroke width around each element, stays inside the viewBox. Inventory integrates the bell into the shelf; permission centers a complete padlock on the panel; product uses a front-facing label. No detached brand decorations. The family specimen uses one site-themed card per scene, four columns on wide screens and two on narrow screens. Opaque neutral bodies must contrast at least 1.3:1 against the actual card background. Use no gradients, shadows or particles; at most one element uses primary-700 in light and primary-900 in dark, with identical geometry. Scene selects list, search, complete, chart, inventory, orders, product or permission. Scene takes precedence over the compatible variant; absent scene, neutral maps to list and all other calls to complete. Standalone complete and EmptyState list defaults intentionally receive new artwork and internal SVG structure. Keep the decorative outer span, aria-hidden=true, non-focusable SVG and text-owned state meaning. Complete owns its check; CheckCircleFill semantics are unchanged.
+Accepted #830: decorative empty illustrations share a 96×104 viewBox, radius-3 outer frames, radius-1 clips, and ICON_STROKE_WIDTH round strokes. All scene geometry, including half the computed stroke width around each element, stays inside the viewBox. Inventory integrates the bell into the shelf; permission centers a complete padlock on the panel; product uses a front-facing label. No detached brand decorations. The family specimen uses one site-themed card per scene, four columns on wide screens and two on narrow screens. Opaque neutral bodies must contrast at least 1.3:1 against the actual card background. Use no gradients, shadows or particles; exactly one element uses primary-700 in light and primary-900 in dark, with identical geometry. Scene selects list, search, complete, chart, inventory, orders, product, permission, purchase, supplier, team, notification, store, task, session or activity. Scene takes precedence over the compatible variant; absent scene, neutral maps to list and all other calls to complete. Standalone complete and EmptyState list defaults intentionally receive new artwork and internal SVG structure. Keep the decorative outer span, aria-hidden=true, non-focusable SVG and text-owned state meaning. Complete owns its check; CheckCircleFill semantics are unchanged.
 
 ### EmptyState illustration-only presentation
 

package/contracts/table-migration.md

@@ -39,6 +39,11 @@ library, router, or product-side data model.
   navigation in this contract.
 - `renderRow` and composed cells may extend row presentation, but they must
   preserve the table's heading, cell, focus, and selection semantics.
+  `TableRowRenderContext<T>.selectionCell: ReactNode | null` exposes the exact
+  complete selection cell used by default rows, including the library Checkbox,
+  accessible name, controlled state, disabled state, and change handler. It is
+  `null` without `selection`. Reuse it when composing content cells; `cells`
+  remains unchanged and still includes the selection cell, so do not render both.
 - Loading, empty, and error states are explicit consumer-owned surfaces. Table
   must not invent fetch status, error copy, recovery actions, or business
   permissions. An empty result may be rendered as an adjacent Empty State
@@ -60,9 +65,25 @@ requires each capability.
 - Selection is controlled by the consumer. Table receives the selected row keys
   and reports the next selected-key collection through its change callback; it
   does not keep an independent authoritative selection store.
+- `onSelectionChange(selectedKeys, details)` keeps the selected-key array contents
+  and ordering unchanged. Existing single-argument callbacks remain assignable.
+  The exported `TableSelectionChangeDetails` is `{ type: 'row' | 'page';
+  rowKey?: TableRowKey; checked: boolean; shiftKey: boolean }`. Row changes include
+  `rowKey`; current-page changes omit the property entirely. `checked` is the
+  control's target state. `shiftKey` reads the triggering native event modifier,
+  defaulting to `false` when absent, including native Shift-click and Shift-Space.
+  These details do not implement range selection or change default selection behavior.
 - A row is selectable only when the consumer exposes it as selectable. Selection
-  controls use native checkboxes with accessible names and a visible
-  `:focus-visible` state.
+  controls use the library `Checkbox` with accessible names and a visible
+  `:focus-visible` state. Header and default row selection share the bare
+  `span.control-option.control-option--bare` shell, native checkbox input, and
+  `span.control-option__visual`. The former `table__checkbox-control` label is
+  removed; consumers targeting it must use the selection cell and Checkbox
+  structure. Both controls have equal visual dimensions and horizontal centers,
+  and their visual centers align vertically with the first text column,
+  retain the selection-column width, and use canonical theme tokens. Coarse
+  pointers retain the minimum touch target. Header `indeterminate` and
+  `aria-checked="mixed"` expose partial selection.
 - The header select-all control operates on the currently rendered/selectable
   page only.
 - Selecting all adds the selectable keys visible on the current page to the

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

@@ -151,20 +151,31 @@ export declare type BadgeTone = 'neutral' | 'info' | 'success' | 'warning' | 'da
 
 export declare function Banner({ title, children, tone, icon, action, onDismiss, progress, className, ...rest }: BannerProps): JSX.Element;
 
+export declare type BannerAction = {
+    label: string;
+    href: string;
+    onClick?: never;
+    loading?: never;
+    disabled?: never;
+} | {
+    label: string;
+    href?: never;
+    onClick: NonNullable<ButtonProps['onClick']>;
+    loading?: ButtonProps['loading'];
+    disabled?: ButtonProps['disabled'];
+};
+
 export declare type BannerProps = {
     /** 粗体导语，一眼点题。 */
     title: string;
-    /** 描述文案；组件统一用「 — 」与导语衔接。 */
+    /** 段落内文本或行内内容，可放 Link；组件统一用「 — 」与导语衔接。 */
     children?: ReactNode;
     /** 未设 = 页顶公告形态；设值 = 页内卡条形态（neutral 为中性卡条）。 */
     tone?: BannerTone;
     /** 卡条形态的前缀图标；纯装饰（组件自动 aria-hidden）。公告形态与进度形态不渲染图标。 */
     icon?: ReactNode;
-    /** 主操作：公告形态渲染恒深药丸（无 chevron）；卡条形态渲染描边药丸 + chevron。进度形态忽略 action——任务进行中不挂主跳转，完成后换普通卡条。 */
-    action?: {
-        label: string;
-        href: string;
-    };
+    /** 主操作链接或按钮；按钮复用 Button 的 loading / disabled。进度形态忽略 action。 */
+    action?: BannerAction;
     /** 关闭回调；设置后渲染关闭按钮。公告形态无关闭；进度形态渲染在进度头右侧。 */
     onDismiss?: () => void;
     /** 进度形态（自有扩展）：value 为 0–100 的百分比（非法值归 0），label 供读屏。进度恒为卡条形态。 */
@@ -1107,7 +1118,7 @@ export declare type EmptyListIllustrationProps = {
     variant?: 'complete' | 'neutral';
 };
 
-export declare type EmptyListIllustrationScene = 'list' | 'search' | 'complete' | 'chart' | 'inventory' | 'orders' | 'product' | 'permission';
+export declare type EmptyListIllustrationScene = 'list' | 'search' | 'complete' | 'chart' | 'inventory' | 'orders' | 'product' | 'permission' | 'purchase' | 'supplier' | 'team' | 'notification' | 'store' | 'task' | 'session' | 'activity';
 
 export declare function EmptyState({ icon, illustration, title, titleHidden, description, actions, headingLevel, layout, }: {
     icon?: ReactNode;
@@ -2691,16 +2702,24 @@ export declare type TableRowRenderContext<T> = {
     rowKey: TableRowKey;
     rowProps: TableHTMLAttributes<HTMLTableRowElement>;
     cells: ReactNode;
+    selectionCell: ReactNode | null;
 };
 
 export declare type TableSelection<T> = {
     selectedKeys: readonly TableRowKey[];
-    onSelectionChange: (selectedKeys: TableRowKey[]) => void;
+    onSelectionChange: (selectedKeys: TableRowKey[], details: TableSelectionChangeDetails) => void;
     getRowLabel: (row: T, rowIndex: number) => string;
     getRowDisabled?: (row: T, rowIndex: number) => boolean;
     selectAllLabel?: string;
 };
 
+export declare type TableSelectionChangeDetails = {
+    type: 'row' | 'page';
+    rowKey?: TableRowKey;
+    checked: boolean;
+    shiftKey: boolean;
+};
+
 export declare type TableSortDirection = 'asc' | 'desc';
 
 export declare function Tabs({ tabs, ariaLabel, variant, value, defaultValue, onValueChange, }: {