@q1travel/design-system 0.1.0 → 0.2.0

package/dist/design-system.d.ts

@@ -7,6 +7,7 @@ import { KeyboardEventHandler } from 'react';
 import { MouseEventHandler } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { Ref } from 'react';
 import { RefObject } from 'react';
 import { SelectHTMLAttributes } from 'react';
 import { TextareaHTMLAttributes } from 'react';
@@ -17,13 +18,13 @@ export declare function Avatar({ title, src, letter, glyph, placeholder, icon, i
 
 export declare function AvatarGroup({ members, label, size, limit, overlap, reverse, className, }: {
     members: AvatarMember[];
-    /** 可选整组名；传入则套 role=group 作整组增强，不传则跟 Geist 默认逐个头像标注（读屏念每个成员名）。 */
+    /** 可选整组名；传入则套 role=group 作整组增强，不传则默认逐个头像标注（读屏念每个成员名）。 */
     label?: string;
     /** 成员统一直径；缺省 32。 */
     size?: number;
     /** 显示上限，超出收纳为 +N；非法值（负数/NaN）忽略。 */
     limit?: number;
-    /** 重叠像素；'auto' = 尺寸的 30% 取整（Geist 实测 16→5 / 24→7 / 32→10 / 48→14）；负数按 0 处理。 */
+    /** 重叠像素；'auto' = 尺寸的 30% 取整（例：16→5 / 24→7 / 32→10 / 48→14）；负数按 0 处理。 */
     overlap?: number | 'auto';
     /** 翻转堆叠顺序。 */
     reverse?: boolean;
@@ -43,7 +44,7 @@ export declare type AvatarProps = {
     glyph?: ReactNode;
     /** 加载占位骨架；只用于加载态，不作长期缺省。 */
     placeholder?: boolean;
-    /** 右下角标图标（对标 Geist With custom icon）；纯装饰，语义信息由调用方文字承载。 */
+    /** 右下角标图标；纯装饰，语义信息由调用方文字承载。 */
     icon?: ReactNode;
     /** 角标底色（任意 CSS color，建议用语义 token）；缺省中性灰盘。 */
     iconColor?: string;
@@ -63,7 +64,7 @@ export declare type BadgeProps = {
     subtle?: boolean;
     /** 反转高对比形态；设置后忽略 tone/subtle。 */
     inverted?: boolean;
-    /** 尺寸档 20/24/32（Geist 实测阶梯）。 */
+    /** 尺寸档 20/24/32。 */
     size?: BadgeSize;
     /** 前置图标；纯装饰（组件自动 aria-hidden），宽高随档位 12/14/16 由样式钉死。 */
     icon?: ReactNode;
@@ -88,12 +89,12 @@ export declare type BannerProps = {
     tone?: BannerTone;
     /** 卡条形态的前缀图标；纯装饰（组件自动 aria-hidden）。公告形态与进度形态不渲染图标。 */
     icon?: ReactNode;
-    /** 主操作：公告形态渲染恒深药丸（无 chevron，Geist 同款）；卡条形态渲染描边药丸 + chevron。进度形态忽略 action——任务进行中不挂主跳转，完成后换普通卡条。 */
+    /** 主操作：公告形态渲染恒深药丸（无 chevron）；卡条形态渲染描边药丸 + chevron。进度形态忽略 action——任务进行中不挂主跳转，完成后换普通卡条。 */
     action?: {
         label: string;
         href: string;
     };
-    /** 关闭回调；设置后渲染关闭按钮。公告形态无关闭（跟 Geist）；进度形态渲染在进度头右侧。 */
+    /** 关闭回调；设置后渲染关闭按钮。公告形态无关闭；进度形态渲染在进度头右侧。 */
     onDismiss?: () => void;
     /** 进度形态（自有扩展）：value 为 0–100 的百分比（非法值归 0），label 供读屏。进度恒为卡条形态。 */
     progress?: {
@@ -111,11 +112,11 @@ export declare function Book({ title, variant, color, bandColor, textColor, icon
 export declare type BookProps = {
     /** 封面标题；语义由标题承载，封面其余元素均为装饰。 */
     title: string;
-    /** stripe=顶部色带+下方标签区（Geist 默认）；simple=纯封面、标题置顶。 */
+    /** stripe=顶部色带+下方标签区（默认）；simple=纯封面、标题置顶。 */
     variant?: 'stripe' | 'simple';
-    /** 封面底色；建议传设计 token（var(--q1-color-…)），勿用裸 hex（Geist Best Practices 同款要求）。 */
+    /** 封面底色；建议传设计 token（var(--q1-color-…)），勿用裸 hex。 */
     color?: string;
-    /** stripe 色带颜色；缺省琥珀（Geist 实测默认带色）。 */
+    /** stripe 色带颜色；缺省琥珀。 */
     bandColor?: string;
     /** 标题颜色；自定义封面色时务必保证对比可读。 */
     textColor?: string;
@@ -123,7 +124,7 @@ export declare type BookProps = {
     icon?: ReactNode;
     /** 整幅插画：铺满封面、裁切；标题浮于其上；aria-hidden。 */
     illustration?: ReactNode;
-    /** 细密交叉纹理（自有配方；Geist 的多款纹理样式记 non-goal）。仅用于主视觉，成排书架勿用。 */
+    /** 细密交叉纹理（自有配方）；只提供单一纹理样式，未做多纹理体系（记 non-goal）。仅用于主视觉，成排书架勿用。 */
     textured?: boolean;
     /** 数字按 px；字符串原样透传（如 clamp(...) 做响应式宽度）。内部排版随宽度等比缩放。
      *  width 是唯一尺寸入口：用 style.width 改宽会与内部缩放脱节。 */
@@ -188,7 +189,7 @@ declare type ButtonProps = {
     iconOnly?: boolean;
     /** 圆形——仅用于 icon-only 按钮。与 rounded 互斥（同传时 circle 优先）。 */
     circle?: boolean;
-    /** 药丸形（full radius）+ 柔和抬起阴影（对标 Geist Rounded，营销页/落地页文字 CTA 用）。与 circle 互斥。 */
+    /** 药丸形（full radius）+ 柔和抬起阴影，营销页/落地页文字 CTA 用。与 circle 互斥。 */
     rounded?: boolean;
     loading?: boolean;
     disabled?: boolean;
@@ -205,6 +206,8 @@ declare type ButtonProps = {
     onFocus?: FocusEventHandler<HTMLButtonElement | HTMLAnchorElement>;
     onBlur?: FocusEventHandler<HTMLButtonElement | HTMLAnchorElement>;
     onKeyDown?: KeyboardEventHandler<HTMLButtonElement | HTMLAnchorElement>;
+    /** 渲染为 <button> 或 <a>（取决于是否传 href），供 focus 管理、测量、浮层定位等场景使用。 */
+    ref?: Ref<HTMLButtonElement | HTMLAnchorElement>;
 };
 
 export declare type ButtonSize = 'sm' | 'md' | 'lg';
@@ -245,13 +248,13 @@ declare type CardOwnProps = {
     hover?: boolean;
     /** 次要表面：更弱的底色，与主卡片区分层级。 */
     secondary?: boolean;
-    /** 分段：用分隔线把卡片切成几段（对齐 Geist borderBetween）。 */
+    /** 分段：用分隔线把卡片切成几段。 */
     divided?: boolean;
     /** 分段方向：column 竖排（默认）/ row 横排。与 divided 正交——单传 row 只横向铺开，配 divided 才加分隔线。 */
     direction?: CardDirection;
-    /** 常驻柔和投影（对齐 Geist shadow）：让卡片浮于背景，用于落地/营销卡片。 */
+    /** 常驻柔和投影：让卡片浮于背景，用于落地/营销卡片。 */
     shadow?: boolean;
-    /** 是否带边框，默认 true。传 false 得无框卡片（靠底色/投影表达边界，对齐 Geist border 可选）。 */
+    /** 是否带边框，默认 true。传 false 得无框卡片（靠底色/投影表达边界）。 */
     bordered?: boolean;
     className?: string;
     children: ReactNode;
@@ -345,7 +348,8 @@ export declare function CodeTokens({ tokens }: {
 }): JSX.Element;
 
 export declare function Collapse({ title, defaultOpen, small, children, }: {
-    title: string;
+    /** 固定文案传字符串；随展开/收起切换文案（如"显示代码"/"收起代码"）传函数，入参为当前 open 状态。 */
+    title: string | ((open: boolean) => string);
     defaultOpen?: boolean;
     small?: boolean;
     children: ReactNode;
@@ -404,7 +408,7 @@ declare type CommandMenuProps = {
 };
 
 export declare type CommandMenuSection = {
-    /** 段标题；缺省时该段以无标题分隔线与上文分隔（对标 Geist CommandMenuDivider）。 */
+    /** 段标题；缺省时该段以无标题分隔线与上文分隔。 */
     heading?: string;
     items: CommandMenuItem[];
 };
@@ -548,7 +552,7 @@ export declare type ErrorMessageSize = 'sm' | 'md' | 'lg';
 export declare function Feedback({ label, prompt, placeholder, inline, topics, }: {
     label?: string;
     prompt?: string;
-    /** textarea 占位（对标 Geist Custom Placeholder）：换成更具体的引导，帮助用户知道从哪里说起。 */
+    /** textarea 占位：换成更具体的引导，帮助用户知道从哪里说起。 */
     placeholder?: string;
     inline?: boolean;
     topics?: string[];
@@ -610,11 +614,11 @@ export declare function Input({ id, label, description, error, prefix, suffix, p
     error?: string;
     prefix?: ReactNode;
     suffix?: ReactNode;
-    /** 置 false 去掉前缀的灰块底色与分隔线，变成纯文本/裸图标（对标 Geist prefixStyling）。 */
+    /** 置 false 去掉前缀的灰块底色与分隔线，变成纯文本/裸图标。 */
     prefixStyling?: boolean;
-    /** 置 false 去掉后缀的灰块底色与分隔线（对标 Geist suffixStyling）。 */
+    /** 置 false 去掉后缀的灰块底色与分隔线。 */
     suffixStyling?: boolean;
-    /** 药丸形全圆角外框（对标 Geist rounded，实测 9999px 级 pill 半径）。 */
+    /** 药丸形全圆角外框（9999px 级 pill 半径）。 */
     rounded?: boolean;
     wide?: boolean;
     size?: FieldSize;
@@ -714,8 +718,8 @@ declare type NativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'id'
 
 declare type NativeInputProps_2 = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>;
 
-export declare function Note({ type, size, filled, disabled, label, action, children, }: {
-    type?: NoteType;
+export declare function Note({ tone, size, filled, disabled, label, action, children, }: {
+    tone?: NoteTone;
     size?: NoteSize;
     filled?: boolean;
     disabled?: boolean;
@@ -726,7 +730,7 @@ export declare function Note({ type, size, filled, disabled, label, action, chil
 
 declare type NoteSize = 'small' | 'default' | 'large';
 
-declare type NoteType = 'info' | 'success' | 'warning' | 'error' | 'secondary';
+export declare type NoteTone = 'info' | 'success' | 'warning' | 'error' | 'secondary';
 
 declare type PageLink = {
     title: string;
@@ -749,7 +753,7 @@ export declare function Phone({ screenLabel }: {
 
 export declare function Pill({ href, size, icon, title, className, children, ...rest }: PillProps): JSX.Element;
 
-declare type PillProps = {
+export declare type PillProps = {
     href: string;
     size?: BadgeSize;
     /** 前置图标；纯装饰（组件自动 aria-hidden）。 */
@@ -799,7 +803,7 @@ export declare function RangeInputs({ value, withTime, onApply, pinnedTimezone,
     value: RangeValue;
     withTime: boolean;
     onApply: () => void;
-    /** 固定时区（对标 Geist pinnedTimezone）：传入时时区从可选 select 变只读文本、不可切换。 */
+    /** 固定时区：传入时时区从可选 select 变只读文本、不可切换。 */
     pinnedTimezone?: string;
 }): JSX.Element;
 
@@ -914,7 +918,7 @@ export declare function Snippet({ text, prompt, inverted, tone, copyText, onCopy
     prompt?: boolean;
     inverted?: boolean;
     tone?: SnippetTone;
-    /** 显示与复制内容分离（对标 Geist）：传了就复制它，不传复制显示内容。 */
+    /** 显示与复制内容分离：传了就复制它，不传复制显示内容。 */
     copyText?: string;
     /** 复制触发后调用，供外部消费复制事件（如埋点）；不代表剪贴板写入一定成功。 */
     onCopy?: () => void;
@@ -1089,6 +1093,12 @@ export declare function useCopy(): {
     reset: () => void;
 };
 
+export declare function useRadio({ id, ...rest }: {
+    id: string;
+} & NativeInputProps): {
+    component: JSX.Element;
+};
+
 export declare function useToast(): ToastContextValue;
 
 export declare function Video({ controls, loop }: {