@q1travel/design-system 0.3.2 → 0.4.0

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

@@ -262,7 +262,7 @@ declare type CardOwnProps = {
 
 export declare type CardProps = CardAsLink | CardAsContainer;
 
-export declare function Checkbox(props: ControlOptionOwnProps & CheckboxOnlyProps & NativeInputProps): JSX.Element;
+export declare function Checkbox({ ...props }: ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & NativeInputProps): JSX.Element;
 
 declare type CheckboxOnlyProps = {
     /** 半选：视觉态而非第三个值，由父级逻辑驱动（如"部分子项已选"）。AT 读作 mixed。 */
@@ -365,10 +365,16 @@ export declare function CollapsibleBreadcrumb({ items, label }: {
     label: string;
 }): JSX.Element;
 
-export declare function Combobox({ options, placeholder, emptyLabel, size, disabled, error, clearable, inputId, }: ComboboxProps): JSX.Element;
+export declare function Combobox({ options, value, onChange, placeholder, size, disabled, readOnly, invalid, errorId, error, emptyText, clearable, id, className, name, inputMode, spellCheck, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ref, ...rest }: ComboboxProps): JSX.Element;
 
 export declare type ComboboxOption = {
+    /** 禁止空字符串（与「未选」的受控空值歧义，adapter 层保证）。 */
     value: string;
+    /** 显示与过滤的唯一来源。 */
+    label: string;
+    disabled?: boolean;
+    /** 组件透而不读，仅随 onChange 第二参原样带回。 */
+    meta?: unknown;
     /** 选项文本前的图标/装饰（如区域旗帜、状态点）。 */
     prefix?: ReactNode;
     /** 选项文本后的图标/装饰（如快捷键、外链标记）。 */
@@ -376,16 +382,41 @@ export declare type ComboboxOption = {
 };
 
 declare type ComboboxProps = {
+    /** 唯一 shape，后端字段在 adapter 层转换。 */
     options: ComboboxOption[];
-    placeholder: string;
-    /** 空状态模板的名词（「没有匹配『查询』的{emptyLabel}」）。 */
-    emptyLabel?: string;
+    /** 受控选中值；'' = 未选。 */
+    value: string;
+    /** 选中传 (option.value, option)；clearable 清除传 ('', undefined)。 */
+    onChange?: (value: string, option?: ComboboxOption) => void;
+    /** 同时作 listbox 的 aria-label。 */
+    placeholder?: string;
+    /** 家族刻度 sm32/md40/lg48（与 Input/Select/Button 同一体系）。 */
     size?: ComboboxSize;
     disabled?: boolean;
+    /** 值只读：不可输入、不展开列表。 */
+    readOnly?: boolean;
+    /** 业务错误模型（主）：置 aria-invalid 与错误描边，文案由外部渲染（配 errorId）。 */
+    invalid?: boolean;
+    /** 外部错误文案元素的 id → aria-describedby；组件不渲染任何文案（外部拥有）。 */
+    errorId?: string;
+    /** 家族便捷（辅）：组件自渲染错误文案并隐含 invalid；与 invalid/errorId 可共存。 */
     error?: string;
+    /** 空态条目；默认业务中立平文案，可传 ReactNode（如带链接的引导）。 */
+    emptyText?: ReactNode;
+    /** 清除按钮 + Esc 二段清除。 */
     clearable?: boolean;
-    /** 供外部 <label htmlFor> 关联；组件自身无 label 属性。 */
-    inputId?: string;
+    /** 施于内部 input，供外部 <label htmlFor> 关联。 */
+    id?: string;
+    className?: string;
+    name?: string;
+    inputMode?: InputHTMLAttributes<HTMLInputElement>['inputMode'];
+    spellCheck?: boolean;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    /** 指向内部 role=combobox 的真实 input（非 wrapper），与内部回焦 ref 合并。 */
+    ref?: Ref<HTMLInputElement>;
+} & {
+    [dataAttr: `data-${string}`]: string | number | boolean | undefined;
 };
 
 export declare type ComboboxSize = 'sm' | 'md' | 'lg';
@@ -452,15 +483,15 @@ export declare type ContextMenuEntry = {
     type: 'separator';
 };
 
-export declare function ControlOption({ id, label, description, error, indeterminate, type, ...rest }: ControlOptionOwnProps & CheckboxOnlyProps & {
+export declare function ControlOption({ id, label, description, error, indeterminate, ref, type, ...rest }: ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & {
     type: 'checkbox' | 'radio';
 } & NativeInputProps): JSX.Element;
 
 declare type ControlOptionOwnProps = {
-    id: string;
-    label: string;
-    description?: string;
-    error?: string;
+    /** 缺省走 useId；显式传入时行为同现状（specimen/测试可寻址）。 */
+    id?: string;
+    /** 指向原生 input（ref-as-prop，React 19），供表头全选聚焦等场景使用；与内部 indeterminate ref 合并。 */
+    ref?: Ref<HTMLInputElement>;
 };
 
 export declare function CopyButton({ value, label, successMessage, size, className, }: {
@@ -516,13 +547,14 @@ export declare function Drawer({ open, onClose, title, children, footer, height,
     height?: number;
 }): JSX.Element | null;
 
-export declare function EmptyState({ icon, title, description, actions, live, }: {
-    icon: ReactNode;
+export declare function EmptyState({ icon, title, description, actions, headingLevel, }: {
+    icon?: ReactNode;
     title: string;
-    description: string;
+    description?: string;
     /** CTA 区：传家族 <Button> 与次要链接；最多一个主 CTA。 */
     actions?: ReactNode;
-    live?: boolean;
+    /** 标题层级：缺省渲染 p（不进标题树）；作为页面区块时传 2-6 渲染对应 h 标签。 */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
 }): JSX.Element;
 
 export declare function Entity({ leading, title, subtitle, trailing, }: {
@@ -558,6 +590,12 @@ export declare function Feedback({ label, prompt, placeholder, inline, topics, }
     topics?: string[];
 }): JSX.Element;
 
+declare type FieldBareProps = {
+    label?: never;
+    description?: never;
+    error?: never;
+};
+
 export declare function Fieldset({ title, subtitle, tone, footerStatus, footerAction, disabled, children, }: {
     title?: string;
     subtitle: string;
@@ -570,6 +608,12 @@ export declare function Fieldset({ title, subtitle, tone, footerStatus, footerAc
 
 export declare type FieldsetTone = 'danger' | 'warning';
 
+declare type FieldShellProps = {
+    label: string;
+    description?: string;
+    error?: string;
+};
+
 export declare type FieldSize = 'xs' | 'sm' | 'md' | 'lg';
 
 export declare function FileTree({ nodes, label, defaultExpanded, }: {
@@ -607,11 +651,15 @@ declare type GaugeSize = 'xs' | 'sm' | 'md' | 'lg';
 
 declare type GaugeToneDirection = 'quota' | 'health';
 
-export declare function Input({ id, label, description, error, prefix, suffix, prefixStyling, suffixStyling, rounded, wide, size, className, ...rest }: {
-    id: string;
-    label: string;
-    description?: string;
-    error?: string;
+export declare function Input({ id, label, description, error, invalid, errorId, ref, prefix, suffix, prefixStyling, suffixStyling, rounded, wide, size, className, ...rest }: {
+    /** 可选：未传时内部 useId 兜底（对齐 Combobox）；显式传入时行为同 0.3.0。 */
+    id?: string;
+    /** 置 aria-invalid 的业务校验态，不渲染文案；与壳模式 error 并轨（invalid || Boolean(error)）。 */
+    invalid?: boolean;
+    /** 业务侧错误文案元素的 id，拼入 aria-describedby；文案由业务层渲染。 */
+    errorId?: string;
+    /** 指向原生 input（ref-as-prop），供校验失败聚焦、测量等场景。 */
+    ref?: Ref<HTMLInputElement>;
     prefix?: ReactNode;
     suffix?: ReactNode;
     /** 置 false 去掉前缀的灰块底色与分隔线，变成纯文本/裸图标。 */
@@ -622,7 +670,7 @@ export declare function Input({ id, label, description, error, prefix, suffix, p
     rounded?: boolean;
     wide?: boolean;
     size?: FieldSize;
-} & Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'size' | 'prefix'>): JSX.Element;
+} & (FieldShellProps | FieldBareProps) & Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'size' | 'prefix'>): JSX.Element;
 
 export declare function Kbd({ meta, shift, alt, ctrl, small, children, }: {
     meta?: boolean;
@@ -784,7 +832,7 @@ export declare function ProjectBanner({ variant, message, cta }: {
     cta: string;
 }): JSX.Element;
 
-export declare function Radio(props: ControlOptionOwnProps & NativeInputProps): JSX.Element;
+export declare function Radio({ ...props }: ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & NativeInputProps): JSX.Element;
 
 export declare function RangeField({ layout, trigger, size, minValue, maxValue, pinnedTimezone, today, value, onChange, }: {
     layout?: PopoverLayout;
@@ -999,14 +1047,18 @@ export declare function Tabs({ tabs, ariaLabel, variant, }: {
     variant?: 'default' | 'secondary';
 }): JSX.Element | null;
 
-export declare function Textarea({ id, label, description, error, wide, size, className, ...rest }: {
-    id: string;
-    label: string;
-    description?: string;
-    error?: string;
+export declare function Textarea({ id, label, description, error, invalid, errorId, ref, wide, size, className, maxLength, onInput, ...rest }: {
+    /** 缺省走 useId；显式传入时行为同现状（specimen/测试可寻址）。 */
+    id?: string;
+    /** 业务校验模型（主）：置 aria-invalid；文案由业务层经 errorId 关联，组件不渲染。 */
+    invalid?: boolean;
+    /** 外部错误文案元素的 id，拼入 aria-describedby；文案由业务层渲染。 */
+    errorId?: string;
+    /** 指向原生 textarea（ref-as-prop，React 19），供校验失败聚焦、测量等场景使用。 */
+    ref?: Ref<HTMLTextAreaElement>;
     wide?: boolean;
     size?: FieldSize;
-} & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'id'>): JSX.Element;
+} & (FieldShellProps | FieldBareProps) & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'id'>): JSX.Element;
 
 export declare function TextWithCopyButton({ text, copyValue, successMessage, size, }: {
     text: string;
@@ -1043,8 +1095,13 @@ export declare function ToastProvider({ children }: {
 
 export declare type ToastTone = 'default' | 'success' | 'warning' | 'error';
 
-export declare function Toggle({ defaultOn, disabled, size, onColor, label, description, labelSide, ariaLabel, }: {
+export declare function Toggle({ checked, defaultOn, onChange, disabled, size, onColor, label, description, labelSide, ariaLabel, }: {
+    /** 受控值；提供后内部状态失效，显示值以外部回写的 checked 为准。 */
+    checked?: boolean;
+    /** 非受控模式的初始值；与 checked 同传时以 checked 为准。 */
     defaultOn?: boolean;
+    /** 切换回调，参数为目标布尔值；受控与非受控模式都会触发。 */
+    onChange?: (checked: boolean) => void;
     disabled?: boolean;
     size?: ToggleSize;
     onColor?: string;