@q1travel/design-system 0.20.0 → 0.22.0

package/contracts/token-naming.md

@@ -28,12 +28,16 @@ Examples:
 - `--q1-font-size-copy-14`
 
 Reference color scales use numeric steps from `100` to `1000`.
+`gray-alpha-100/200` are theme-relative translucent neutral overlays (black 6%/8%
+in light mode, white 8%/12% in dark mode); use them for list states and quiet borders.
+Strong heading roles (`heading-40/32/24/20-strong`) preserve each size and line box
+while opting into weight 600. Existing heading roles remain weight 500.
 
 #### Scale Steps
 
 Non-color reference scales carry their own step rules, so a value that is off the scale shows up as a missing token rather than as a raw number in product CSS.
 
-- **Spacing** — the step number is the pixel value divided by four: `--q1-space-4` is `16px`. Half steps fill the gaps inside the 4px grid where a whole step reads as too loose or too tight: `--q1-space-1-5` (`6px`), `--q1-space-2-5` (`10px`), `--q1-space-3-5` (`14px`). The scale runs `1`, `1-5`, `2`, `2-5`, `3`, `3-5`, `4`, `5`, `6`, `8`, `10`, `16`, `24`; it thins out above `20px` because a large gap is read as layout, not as fine adjustment.
+- **Spacing** — the step number is the pixel value divided by four: `--q1-space-4` is `16px`. Half steps fill the gaps inside the 4px grid where a whole step reads as too loose or too tight: `--q1-space-1-5` (`6px`), `--q1-space-2-5` (`10px`), `--q1-space-3-5` (`14px`). The scale runs `1`, `1-5`, `2`, `2-5`, `3`, `3-5`, `4`, `5`, `6`, `7`, `8`, `10`, `16`, `24`; it thins out above `20px` because a large gap is read as layout, not as fine adjustment.
 - **Radius** — `--q1-radius-1` through `--q1-radius-5` (`4`, `6`, `8`, `12`, `16px`), plus `--q1-radius-full` (`9999px`) for a pill. The pill value is deliberately larger than any half-height it can meet: it is a shape, not a measurement, and it does not interpolate with the numbered steps.
 - **Line height** — two families coexist. `--q1-line-height-<role>-<size>` is a pixel line box bound to one font-size step, and typography styles use it. `--q1-line-height-tight` (`1.2`), `-snug` (`1.35`), `-normal` (`1.5`), and `-relaxed` (`1.6`) are unitless and scale with whatever font size they land on; they serve text whose size is not one of the typography steps, such as a body block or a table cell.
 - **Font weight** — `--q1-font-weight-regular` (`400`), `-medium` (`500`), `-semibold` (`600`), `-bold` (`700`). Four steps is the whole scale; a weight between two of them is not a distinction the font stack renders consistently.
@@ -73,6 +77,8 @@ Their values hold only for the font stack they were measured with. The package d
 - `--q1-button-hang-inline` (`calc(var(--q1-space-3) + 1px)`) — distance from a small button's border edge to its label. Ghost buttons in a table actions column hang by this amount so the label starts on the column line.
 - `--q1-badge-optical-shift` (`0px`) and `--q1-button-affix-optical-y` (`0px`) — opt-in switches for the Badge label and Button affixes. They default to zero because Chinese and Latin labels move in opposite directions; a consumer sets them only where the label script is known.
 
+The CJK heading and multiline-copy line boxes are independent of these label calibrations. `label-13` remains 18px and the default media offset remains `-3px`; changing heading/copy line heights does not change that first-line box. Note uses its own 1.5 line height, and ProductLockup uses the unchanged heading-16/14 line boxes. Re-measure the optical fixture before changing any compensation; the 1px tolerance remains unchanged.
+
 Rules:
 
 - Values are whole pixels. A compensation never uses a fractional pixel such as `0.5px`.
@@ -96,9 +102,13 @@ Examples:
 
 `--q1-color-status-danger` is the bright red for fills and strokes only; use `--q1-color-status-danger-text` for text and weak notices without an underline. `--q1-color-status-danger-surface` and `--q1-color-status-danger-border` keep the background and stroke roles separate. `--q1-color-text-soft`, `--q1-color-border-subtle`, and `--q1-color-overlay-scrim` cover tertiary text, quiet separators, and overlay scrims.
 
-`--q1-color-focus` resolves to `--q1-color-primary-700` in light mode and `--q1-color-primary-900` in dark mode. `--q1-shadow-focus` draws a 2px canvas gap and a 2px focus ring for controls that use a shadow. Button-family controls use a 2px outline with a 2px offset; inputs use `--q1-color-border-active` plus a 1px inset stroke and the gapless translucent `--q1-shadow-focus-input` glow for pointer and keyboard focus. Invalid inputs use `--q1-shadow-focus-input-danger` for a red inset stroke and glow. Text links keep a fine underline at rest, deepen it on hover, and use a 3px focus-color underline for keyboard focus. Forced colors use a system Highlight outline.
+Owner-approved exception (2026-10-05): ErrorMessage, field errors, and ErrorCard titles use `--q1-color-red-900`; other status text retains its existing semantic text token.
+
+`--q1-color-focus` is neutral black in light mode and white in dark mode. `--q1-shadow-focus` and `--q1-shadow-focus-input` use a gapless 1px ring at 34% plus a 4px halo at 16%. Buttons and inputs consume this recipe; input focus preserves the resting border, without an active-border swap or inset stroke. `--q1-input-border-focus` remains an opt-in override and defaults to the resting input border. Invalid inputs retain their danger border; `--q1-shadow-focus-input-danger` and `--q1-shadow-focus-danger` use the same 1px / 4px geometry with danger color at 34% / 16%. Text links retain the 3px neutral focus underline. Forced colors and high contrast retain visible system outlines.
+
+Migration: `--q1-color-bg-panel` remains `#ffffff` in light mode and changes from `#0a0a0a` to `#1a1a1a` in dark mode. The dark canvas, raised surface, and overlay now use `#121212`, `#222222`, and `#2b2b2b`. Downstream overrides that manually raised panel or overlay backgrounds should be reviewed. The 2026-10-05 owner-approved focus change replaces the brand ring and inset input stroke with the neutral 1px / 4px recipe and preserves resting input borders. Consumers with custom focus visuals should update their screenshots and forced-colors fallback. The unused `--q1-shadow-card` name is removed before release.
 
-Migration: `--q1-color-bg-panel` remains `#ffffff` in light mode and changes from `#0a0a0a` to `#1a1a1a` in dark mode. The dark canvas, raised surface, and overlay now use `#121212`, `#222222`, and `#2b2b2b`. Downstream overrides that manually raised panel or overlay backgrounds should be reviewed. `--q1-shadow-focus` keeps a canvas gap and uses a 2px focus ring; input focus adds a 1px inset stroke while preserving the translucent glow. Consumers with custom focus visuals should update their screenshots and forced-colors fallback. The unused `--q1-shadow-card` name is removed before release.
+`--q1-touch-target-min` (`44px`) is the theme-independent semantic minimum for coarse-pointer hit regions, stored as `sizing.touch-target-min` in both theme contracts. It changes the invisible target, not the visual size.
 
 ### Component Tokens
 

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

@@ -1,5 +1,6 @@
 import { AnchorHTMLAttributes } from 'react';
 import { ButtonHTMLAttributes } from 'react';
+import { ComponentProps } from 'react';
 import { ComponentPropsWithoutRef } from 'react';
 import { CSSProperties } from 'react';
 import { FocusEventHandler } from 'react';
@@ -22,6 +23,18 @@ import { TextareaHTMLAttributes } from 'react';
 
 export declare function addDays(date: Date, amount: number): Date;
 
+export declare function Attachment({ name, size, type, progress, error, onRetry, onRemove, }: AttachmentProps): JSX.Element;
+
+export declare type AttachmentProps = {
+    name: string;
+    size?: ReactNode;
+    type?: 'file' | 'image';
+    progress?: number;
+    error?: ReactNode;
+    onRetry?: () => void;
+    onRemove?: () => void;
+};
+
 export declare function AuthCard({ title, description, action, className }: AuthCardProps): JSX.Element;
 
 /** Focused presentational card for account entry and connection flows. */
@@ -302,6 +315,9 @@ export declare type ButtonSize = 'sm' | 'md' | 'lg';
 
 export declare type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'warning' | 'danger';
 
+/** 标准日期区间选择器；复用 RangeField 的草稿、弹层和键盘行为。 */
+export declare function Calendar(props: CalendarProps): JSX.Element;
+
 export declare function CalendarGrid({ value, onChange, size, minValue, maxValue, today, }: {
     value: RangeValue;
     onChange: (next: RangeValue) => void;
@@ -316,6 +332,8 @@ export declare type CalendarPreset = {
     getRange: () => RangeValue;
 };
 
+export declare type CalendarProps = ComponentProps<typeof RangeField>;
+
 export declare type CalendarSize = 'large' | 'small';
 
 export declare function Card(props: CardProps): JSX.Element;
@@ -435,6 +453,8 @@ export declare function CodeBlock(props: CodeBlockProps): JSX.Element;
 
 declare type CodeBlockBaseProps = {
     lineNumbers?: boolean;
+    /** flush 用于 ShowCode 等已有边框的嵌入表面；默认保留独立代码块。 */
+    variant?: 'default' | 'flush';
 };
 
 export declare type CodeBlockLine = {
@@ -476,8 +496,8 @@ export declare function Collapse({ title, defaultOpen, small, headingLevel, chil
     title: string | ((open: boolean) => string);
     defaultOpen?: boolean;
     small?: boolean;
-    /** 标题层级：默认 h3；按宿主页面的标题树传 1-6。 */
-    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** 标题层级：默认 h3；按宿主页面的标题树传 1-6，附属 disclosure 传 null 不加入标题树。 */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6 | null;
     children: ReactNode;
 }): JSX.Element;
 
@@ -525,7 +545,7 @@ export declare type ComboboxProps = {
     disabled?: boolean;
     /** 值只读：不可输入、不展开列表。 */
     readOnly?: boolean;
-    /** 业务错误模型（主）：置 aria-invalid 与错误描边，文案由外部渲染（配 errorId）。 */
+    /** 业务错误模型（主）：置 aria-invalid 与错误环，文案由外部渲染（配 errorId）。 */
     invalid?: boolean;
     /** 外部错误文案元素的 id → aria-describedby；组件不渲染任何文案（外部拥有）。 */
     errorId?: string;
@@ -576,6 +596,27 @@ export declare type CommandMenuSection = {
     items: CommandMenuItem[];
 };
 
+export declare function Composer({ onSubmit, onAttach, attachments, mentions, disabled, }: ComposerProps): JSX.Element;
+
+export declare type ComposerMention = {
+    id: string;
+    label: string;
+    description?: string;
+};
+
+export declare type ComposerProps = {
+    onSubmit: (submission: ComposerSubmission) => void;
+    onAttach?: () => void;
+    attachments?: ReactNode;
+    mentions?: ComposerMention[];
+    disabled?: boolean;
+};
+
+export declare type ComposerSubmission = {
+    text: string;
+    mentionIds: string[];
+};
+
 export declare function ContextCard({ name, identity, rows, action, onAction, actionHref, placement, align, children, }: ContextCardProps): JSX.Element;
 
 declare type ContextCardAction = {
@@ -743,6 +784,16 @@ export declare function CopyButton({ value, label, successMessage, size, classNa
     className?: string;
 }): JSX.Element;
 
+export declare type CopyFeedbackOptions = {
+    /**
+     * 成功反馈：'toast'（默认）经共享 Toast 播报；'inline' 只切换就地对勾，由调用方提供读屏播报。
+     * 失败始终弹错误 Toast——只靠图标，用户可能注意不到复制没有成功。
+     */
+    success?: 'toast' | 'inline';
+    /** 对勾保持的时长（毫秒），默认 1500。 */
+    resetAfterMs?: number;
+};
+
 export declare function Description({ title, tooltip, align, ellipsis, children, }: {
     title: string;
     tooltip?: string;
@@ -911,6 +962,16 @@ export declare type FileTreeNode = {
     children?: FileTreeNode[];
 };
 
+/** 筛选选择器入口；弹层、筛选值与 expanded 状态归调用方。 */
+export declare function FilterChip({ label, value, onClear, disabled, className, ...props }: FilterChipProps): JSX.Element;
+
+export declare type FilterChipProps = {
+    label: string;
+    /** undefined 表示未设置；0、空字符串和 null 仍是已设置。 */
+    value?: ReactNode;
+    onClear?: () => void;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'value'>;
+
 export declare function FormField({ controlId, label, description, error, wide, children, }: {
     controlId: string;
     label: string;
@@ -1011,6 +1072,35 @@ export declare function Input({ id, label, description, error, invalid, errorId,
     size?: FieldSize;
 } & (FieldShellProps | FieldBareProps) & Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'size' | 'prefix'>): JSX.Element;
 
+export declare function InputOTP({ id, name, value, onValueChange, disabled, readOnly, required, invalid, errorId, size, separator, ref, label, description, error, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': describedBy, }: InputOTPProps): JSX.Element;
+
+export declare type InputOTPProps = {
+    id?: string;
+    name?: string;
+    /** 受控的 0–6 位 ASCII 数字字符串；保留前导零。 */
+    value: string;
+    onValueChange: (value: string) => void;
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    invalid?: boolean;
+    errorId?: string;
+    size?: 'md' | 'lg';
+    /** 显式显示 3+3 分组；默认六格相连，无分隔符。 */
+    separator?: boolean;
+    ref?: Ref<HTMLInputElement>;
+    'aria-describedby'?: string;
+} & ((FieldShellProps & {
+    'aria-label'?: never;
+    'aria-labelledby'?: never;
+}) | (FieldBareProps & ({
+    'aria-label': string;
+    'aria-labelledby'?: never;
+} | {
+    'aria-labelledby': string;
+    'aria-label'?: never;
+})));
+
 export declare function JsonView({ value, singleLine, wrap, collapsedDepth, highlight, embedded, label, className, }: JsonViewProps): JSX.Element;
 
 export declare type JsonViewProps = {
@@ -1098,6 +1188,21 @@ declare type LoadMoreButtonOwnProps = {
 
 export declare type LoadMoreButtonProps = LoadMoreButtonOwnProps & Omit<ComponentPropsWithoutRef<'button'>, keyof LoadMoreButtonOwnProps>;
 
+export declare function Marker({ actor, time, variant, children, }: MarkerProps): JSX.Element;
+
+export declare type MarkerProps = {
+    actor?: ReactNode;
+    time?: ReactNode;
+    variant?: 'default' | 'separator';
+    children: ReactNode;
+};
+
+export declare function Mention({ children }: MentionProps): JSX.Element;
+
+export declare type MentionProps = {
+    children: ReactNode;
+};
+
 export declare function Menu({ label, entries, withChevron, align, triggerContent }: {
     label: string;
     entries: MenuEntry[];
@@ -1160,6 +1265,19 @@ declare type MenuLinkBase = {
     suffix?: ReactNode;
 };
 
+export declare function Message({ author, avatar, time, children, attachments, actions, status, onRetry, }: MessageProps): JSX.Element;
+
+export declare type MessageProps = {
+    author: ReactNode;
+    avatar?: ReactNode;
+    time?: ReactNode;
+    children: ReactNode;
+    attachments?: ReactNode;
+    actions?: ReactNode;
+    status?: 'default' | 'pending' | 'failed';
+    onRetry?: () => void;
+};
+
 export declare function MiddleTruncate({ text, tailLength, mono }: {
     text: string;
     tailLength?: number;
@@ -1332,6 +1450,29 @@ export declare type OverlaySnapshot = {
     readonly blockingCount: number;
 };
 
+export declare function PageFeedback({ variant, onSubmit, contactConsent, privacyHref }: PageFeedbackProps): JSX.Element;
+
+export declare type PageFeedbackPayload = {
+    scale: 'rating4';
+    rating: PageFeedbackRating;
+    comment: string;
+    contactConsent: boolean;
+} | {
+    scale: 'helpful';
+    rating: 'yes' | 'no';
+    comment: string;
+    contactConsent: boolean;
+};
+
+export declare type PageFeedbackProps = {
+    variant: 'rating' | 'helpful';
+    onSubmit: (payload: PageFeedbackPayload) => Promise<void>;
+    contactConsent?: boolean;
+    privacyHref?: string;
+};
+
+export declare type PageFeedbackRating = 'not-great' | 'okay' | 'good' | 'love';
+
 export declare function Pagination({ page, pageSize: pageSizeProp, total, totalPages: totalPagesProp, hasNextPage, onChange, loading, showPageNumbers, summary, pageSizeSlot, prevLabel, nextLabel, compact, className, }: PaginationProps): JSX.Element;
 
 export declare type PaginationCommonProps = {
@@ -1384,11 +1525,11 @@ export declare type PopoverLayout = 'vertical' | 'horizontal';
 export declare function ProductLockup({ name, icon, brand, size, className, 'aria-label': ariaLabel, ...rest }: ProductLockupProps): JSX.Element;
 
 export declare type ProductLockupProps = {
-    /** 产品名称，以文字渲染，随主题承色。 */
+    /** 产品名称。 */
     name: string;
-    /** 产品图标，视为装饰，不参与朗读。默认为品牌符号。 */
+    /** 替换左侧品牌符号的产品图标。只起装饰作用，读屏不读。默认为奇异旅行的品牌符号。 */
     icon?: ReactNode;
-    /** 背书品牌名，渲染为「by {brand}」。 */
+    /** 显示在「by」后面的品牌名，例如「奇异旅行」或「q1Travel」。 */
     brand?: string;
     size?: ProductLockupSize;
 } & Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'role'>;
@@ -1436,10 +1577,12 @@ export declare function Radio({ ...props }: RadioProps): JSX.Element;
 /** Radio 的完整 props。 */
 export declare type RadioProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & ControlOptionNativeInputProps;
 
-export declare function RangeField({ layout, trigger, size, minValue, maxValue, pinnedTimezone, today, value, onChange, }: {
+export declare function RangeField({ layout, trigger, size, fieldSize, minValue, maxValue, pinnedTimezone, today, value, onChange, }: {
     layout?: PopoverLayout;
     trigger?: TriggerKind;
     size?: CalendarSize;
+    /** 仅控制触发器高度；size 保留月历网格的 large/small 尺寸语义。 */
+    fieldSize?: FieldSize;
     minValue?: Date;
     maxValue?: Date;
     pinnedTimezone?: string;
@@ -1742,10 +1885,9 @@ export declare type SplitButtonEntry = {
     onSelect?: () => void;
 };
 
-export declare function StatusDot({ tone, label, animated, showLabel, titlePrefix, }: {
+export declare function StatusDot({ tone, label, showLabel, titlePrefix, }: {
     tone: StatusDotTone;
     label: string;
-    animated?: boolean;
     showLabel?: boolean;
     titlePrefix?: string;
 }): JSX.Element;
@@ -1860,10 +2002,13 @@ export declare type TableSelection<T> = {
 
 export declare type TableSortDirection = 'asc' | 'desc';
 
-export declare function Tabs({ tabs, ariaLabel, variant, }: {
+export declare function Tabs({ tabs, ariaLabel, variant, value, defaultValue, onValueChange, }: {
     tabs: TabItem[];
     ariaLabel: string;
     variant?: 'default' | 'secondary';
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (id: string) => void;
 }): JSX.Element | null;
 
 export declare function Textarea({ id, label, description, error, invalid, errorId, ref, wide, size, className, maxLength, onInput, ...rest }: TextareaProps): JSX.Element;
@@ -1889,13 +2034,32 @@ export declare function TextWithCopyButton({ text, copyValue, successMessage, si
     size?: 'default' | 'small';
 }): JSX.Element;
 
-export declare function ThemeSwitcher({ small, disabled }: {
+export declare type ThemeMode = 'system' | 'light' | 'dark';
+
+export declare function ThemeSwitcher({ small, disabled, mode, onModeChange }: ThemeSwitcherProps): JSX.Element;
+
+export declare type ThemeSwitcherProps = {
     small?: boolean;
     disabled?: boolean;
-}): JSX.Element;
+    /** 传入即为受控：选中项完全由 mode 决定，组件不读写页面主题、本地存储或全局主题状态。 */
+    mode?: ThemeMode;
+    /** 受控用法下用户选择某一档时调用；组件自身不改变任何状态。 */
+    onModeChange?: (mode: ThemeMode) => void;
+};
 
 export declare type ThresholdTone = 'primary' | 'success' | 'warning' | 'danger';
 
+export declare function Timeline({ className, ...props }: TimelineProps): JSX.Element;
+
+export declare function TimelineItem({ tone, indicator, children, className, ...props }: TimelineItemProps): JSX.Element;
+
+export declare type TimelineItemProps = HTMLAttributes<HTMLLIElement> & {
+    tone?: 'neutral' | 'success' | 'danger' | 'warning';
+    indicator?: ReactNode;
+};
+
+export declare type TimelineProps = HTMLAttributes<HTMLOListElement>;
+
 declare type ToastAction = {
     label: string;
     /** 点击后先执行回调再关闭该提示。 */
@@ -2002,7 +2166,7 @@ export declare type UnknownTailPaginationProps = PaginationCommonProps & {
     showPageNumbers?: false;
 };
 
-export declare function useCopy(): {
+export declare function useCopy({ success, resetAfterMs }?: CopyFeedbackOptions): {
     copied: boolean;
     pending: boolean;
     copy: (value: string, successMessage?: string) => Promise<void>;
@@ -2020,33 +2184,6 @@ export declare type UseRadioOptions = {
 
 export declare function useToast(): ToastContextValue;
 
-export declare function VerificationCodeInput({ id, name, value, onValueChange, disabled, readOnly, required, invalid, errorId, size, ref, label, description, error, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': describedBy, }: VerificationCodeInputProps): JSX.Element;
-
-export declare type VerificationCodeInputProps = {
-    id?: string;
-    name?: string;
-    /** 受控的 0–6 位 ASCII 数字字符串；保留前导零。 */
-    value: string;
-    onValueChange: (value: string) => void;
-    disabled?: boolean;
-    readOnly?: boolean;
-    required?: boolean;
-    invalid?: boolean;
-    errorId?: string;
-    size?: 'md' | 'lg';
-    ref?: Ref<HTMLInputElement>;
-    'aria-describedby'?: string;
-} & ((FieldShellProps & {
-    'aria-label'?: never;
-    'aria-labelledby'?: never;
-}) | (FieldBareProps & ({
-    'aria-label': string;
-    'aria-labelledby'?: never;
-} | {
-    'aria-labelledby': string;
-    'aria-label'?: never;
-})));
-
 export declare function Video({ src, poster, tracks, label, purpose, controls, loop, muted, }: VideoProps): JSX.Element;
 
 declare type VideoBaseProps = {