@ray-js/components 1.7.79 → 1.7.80

package/lib/Input/props.d.ts

@@ -1,95 +1,103 @@
-import { GenericEvent } from '@ray-js/adapter';
-import { BaseProps } from '../types';
 import * as React from 'react';
+import { BaseProps } from '../types';
+import { BaseEvent } from '@ray-js/adapter';
 export type InputType = 'text' | 'number' | 'digit' | 'idcard';
+/** input 输入事件数据 */
+export interface InputInputDetail {
+    /** 输入框内容 */
+    value: string;
+    /** 光标位置 */
+    cursor: number;
+    /** 键值 */
+    keyCode: number;
+}
+/** input 通用文本事件数据 */
+export interface InputValueDetail {
+    /** 输入框内容 */
+    value: string;
+}
+/** input 输入事件对象 */
+export interface InputInputEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'input';
+    /** 事件数据 */
+    detail: InputInputDetail;
+    /** 输入框当前值 */
+    value: string;
+}
+/** input 确认事件对象 */
+export interface InputConfirmEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'confirm';
+    /** 事件数据 */
+    detail: InputValueDetail;
+}
+/** input 聚焦事件对象 */
+export interface InputFocusEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'focus';
+    /** 事件数据 */
+    detail: InputValueDetail;
+}
+/** input 失焦事件对象 */
+export interface InputBlurEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'blur';
+    /** 事件数据 */
+    detail: InputValueDetail;
+}
+/**
+ * 输入框组件，支持多种输入类型和键盘配置。
+ *
+ * @public
+ * @alias Input
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example 不同类型 ./demos/types/index.tsx sandbox ide e2e
+ * @example 输入限制与禁用 ./demos/limit-disabled/index.tsx sandbox ide e2e
+ */
 export interface InputProps extends BaseProps {
-    /**
-     * @description.en content
-     * @description.zh 内容
-     * @default undefined
-     */
+    /** 输入框的内容 */
     value?: string;
-    /**
-     * @description.en type
-     * @description.zh 类型
-     * @default text
-     */
+    /** 输入类型 */
     type?: InputType;
-    /**
-     * @description.en is password
-     * @description.zh 是否为密码
-     * @default false
-     */
+    /** 表单控件名称，提交表单时作为键名 */
+    name?: string;
+    /** 是否为密码输入框 */
     password?: boolean;
-    /**
-     * @description.en placeholder
-     * @description.zh 占位内容
-     * @default undefined
-     */
+    /** 输入框为空时占位符 */
     placeholder?: string;
-    /**
-     * @description.en placeholder
-     * @description.zh 占位符的样式
-     * @default undefined
-     */
+    /** 占位符的样式 */
     placeholderStyle?: React.CSSProperties | string;
-    /**
-     * @description.en disabled
-     * @description.zh 是否禁用
-     * @default false
-     */
+    /** 是否禁用 */
     disabled?: boolean;
-    /**
-     * @description.en Maximum input length. When the value is set to -1, the maximum input length is not limited
-     * @description.zh 最大输入长度，设置为 -1 的时候不限制最大长度
-     * @default undefined
-     */
+    /** 最大输入长度，设置为 -1 的时候不限制最大长度 */
     maxLength?: number;
-    /**
-     * @description.en Set the text of the button in the lower right corner of the keyboard, effective only when type='text'
-     * @description.zh 设置键盘右下角按钮的文字，仅在type='text'时生效
-     * @default done
-     */
+    /** 设置键盘右下角按钮的文字，仅在 type='text' 时生效 */
     confirmType?: 'send' | 'search' | 'next' | 'go' | 'done';
     /**
-     * @description 输入框内容左侧内容缩进，仅在涂鸦小程序有效
+     * 输入框内容左侧内容缩进，仅在涂鸦小程序有效
+     * @internal
      */
     indentStart?: string | number;
     /**
-     * @description 输入框内容右侧内容缩进，仅在涂鸦小程序有效
+     * 输入框内容右侧内容缩进，仅在涂鸦小程序有效
+     * @internal
      */
     indentEnd?: string | number;
-    /**
-     * @description.en Input events
-     * @description.zh 输入事件
-     * @default undefined
-     */
-    onInput?: (event: GenericEvent<{
-        value: any;
-    }>) => void;
-    /**
-     * @description.en onConfirm
-     * @description.zh 确认事件
-     * @default undefined
-     */
-    onConfirm?: (event: GenericEvent<{
-        value: any;
-    }>) => void;
-    /**
-     * @description.en onFocus
-     * @description.zh 焦点事件
-     * @default undefined
-     */
-    onFocus?: (event: GenericEvent<{
-        value: any;
-    }>) => void;
-    /**
-     * @description.en onBlur
-     * @description.zh 丢焦事件
-     * @default undefined
-     */
-    onBlur?: (event: GenericEvent<{
-        value: any;
-    }>) => void;
+    /** 键盘输入时触发 */
+    onInput?: (event: InputInputEvent) => void;
+    /** 点击完成按钮时触发 */
+    onConfirm?: (event: InputConfirmEvent) => void;
+    /** 输入框聚焦时触发 */
+    onFocus?: (event: InputFocusEvent) => void;
+    /** 输入框失去焦点时触发 */
+    onBlur?: (event: InputBlurEvent) => void;
 }
+/**
+ * Input 组件默认值
+ *
+ * @belong Input
+ * @defaults
+ */
 export declare const defaultInputProps: Partial<InputProps>;

package/lib/Input/props.js

@@ -1,3 +1,32 @@
+/** input 输入事件数据 */
+
+/** input 通用文本事件数据 */
+
+/** input 输入事件对象 */
+
+/** input 确认事件对象 */
+
+/** input 聚焦事件对象 */
+
+/** input 失焦事件对象 */
+
+/**
+ * 输入框组件，支持多种输入类型和键盘配置。
+ *
+ * @public
+ * @alias Input
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example 不同类型 ./demos/types/index.tsx sandbox ide e2e
+ * @example 输入限制与禁用 ./demos/limit-disabled/index.tsx sandbox ide e2e
+ */
+
+/**
+ * Input 组件默认值
+ *
+ * @belong Input
+ * @defaults
+ */
 export const defaultInputProps = {
   type: 'text',
   maxLength: 140,

package/lib/Label/props.d.ts

@@ -1,9 +1,24 @@
 import { BaseProps } from '../types';
+/**
+ * 标签，用于提升表单可用性：可通过 htmlFor 关联控件，或包裹控件扩大点击区域。
+ *
+ * @public
+ * @alias Label
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ *
+ * @example htmlFor 绑定 ./demos/html-for/index.tsx sandbox ide e2e
+ */
 export interface LabelProps extends BaseProps {
     /**
-     * @description.en htmlFor
-     * @description.zh htmlfor
-     * @default undefined
+     * 绑定控件的 id
      */
     htmlFor?: string;
 }
+/**
+ * Label 组件文档用默认值（与运行时 defaultProps 分离）
+ *
+ * @belong Label
+ * @defaults
+ */
+export declare const labelDefaultProps: Partial<LabelProps>;

package/lib/Label/props.js

@@ -1 +1,18 @@
-export {};
+/**
+ * 标签，用于提升表单可用性：可通过 htmlFor 关联控件，或包裹控件扩大点击区域。
+ *
+ * @public
+ * @alias Label
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ *
+ * @example htmlFor 绑定 ./demos/html-for/index.tsx sandbox ide e2e
+ */
+
+/**
+ * Label 组件文档用默认值（与运行时 defaultProps 分离）
+ *
+ * @belong Label
+ * @defaults
+ */
+export const labelDefaultProps = {};

package/lib/PageContainer/props.d.ts

@@ -1,26 +1,57 @@
-import { BaseProps } from '../types';
 import * as React from 'react';
-import { GenericEvent } from '@ray-js/adapter';
-export type PageContainerEventType = GenericEvent<{
-    value: any;
-}>;
-export type PageContainerProps = BaseProps & {
-    /** 文本是否可选 */
+import { BaseProps } from '../types';
+import { BaseEvent } from '@ray-js/adapter';
+/**
+ * 页面容器，用于从屏幕边缘或底部弹出半屏/全屏内容，支持遮罩、圆角、进入离开动画及生命周期回调。
+ *
+ * @public
+ * @alias PageContainer
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example 从底部弹出带遮罩 ./demos/bottom-overlay/index.tsx sandbox ide e2e
+ * @example 自定义样式与生命周期 ./demos/custom-style-lifecycle/index.tsx sandbox ide e2e
+ */
+export interface PageContainerProps extends BaseProps {
+    /** 是否显示容器组件 */
     show?: boolean;
+    /** 动画时长，单位毫秒 */
     duration?: number;
+    /** z-index 层级 */
     zIndex?: number;
+    /** 是否显示遮罩层 */
     overlay?: boolean;
+    /** 弹出位置 */
     position?: 'top' | 'bottom' | 'right' | 'center';
+    /** 是否显示圆角 */
     round?: boolean;
+    /** 自定义遮罩层样式 */
     overlayStyle?: string | React.CSSProperties;
+    /** 自定义弹出层样式 */
     customStyle?: string | React.CSSProperties;
-    onBeforeEnter?: (event: PageContainerEventType) => void;
-    onEnter?: (event: PageContainerEventType) => void;
-    onAfterEnter?: (event: PageContainerEventType) => void;
-    onBeforeLeave?: (event: PageContainerEventType) => void;
-    onLeave?: (event: PageContainerEventType) => void;
-    onAfterLeave?: (event: PageContainerEventType) => void;
-    onClickOverlay?: (event: PageContainerEventType) => void;
-    children?: React.ReactNode | string;
-};
+    /** 进入前触发 */
+    onBeforeEnter?: (event: BaseEvent) => void;
+    /** 进入中触发 */
+    onEnter?: (event: BaseEvent) => void;
+    /** 进入后触发 */
+    onAfterEnter?: (event: BaseEvent) => void;
+    /** 离开前触发 */
+    onBeforeLeave?: (event: BaseEvent) => void;
+    /** 离开中触发 */
+    onLeave?: (event: BaseEvent) => void;
+    /** 离开后触发 */
+    onAfterLeave?: (event: BaseEvent) => void;
+    /** 点击遮罩层时触发 */
+    onClickOverlay?: (event: BaseEvent) => void;
+}
+/**
+ * PageContainer 组件默认值
+ *
+ * @belong PageContainer
+ * @defaults
+ */
 export declare const defaultPageContainerProps: Partial<PageContainerProps>;
+/**
+ * @internal
+ * @deprecated 使用 BaseEvent 替代
+ */
+export type PageContainerEventType = BaseEvent;

package/lib/PageContainer/props.js

@@ -1,3 +1,20 @@
+/**
+ * 页面容器，用于从屏幕边缘或底部弹出半屏/全屏内容，支持遮罩、圆角、进入离开动画及生命周期回调。
+ *
+ * @public
+ * @alias PageContainer
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example 从底部弹出带遮罩 ./demos/bottom-overlay/index.tsx sandbox ide e2e
+ * @example 自定义样式与生命周期 ./demos/custom-style-lifecycle/index.tsx sandbox ide e2e
+ */
+
+/**
+ * PageContainer 组件默认值
+ *
+ * @belong PageContainer
+ * @defaults
+ */
 export const defaultPageContainerProps = {
   show: false,
   duration: 300,
@@ -6,4 +23,9 @@ export const defaultPageContainerProps = {
   position: 'bottom',
   round: false
   // closeOnSlideDown: false,
-};
+};
+
+/**
+ * @internal
+ * @deprecated 使用 BaseEvent 替代
+ */

package/lib/Radio/props.d.ts

@@ -1,27 +1,32 @@
 import { BaseProps } from '../types';
+/**
+ * 单选框，用于在一组互斥选项中选中其中一项。
+ *
+ * @public
+ * @alias Radio
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ *
+ * @example 不同状态 ./demos/states/index.tsx sandbox ide e2e
+ */
 export interface RadioProps extends BaseProps {
-    /**
-     * @description.en Radio id. When the radio is selected, the radio.group change event carries the value of the radio
-     * @description.zh radio 标识。当该 radio 选中时，Radio.Group 的 change 事件会携带 radio 的 value
-     * @default undefined
-     */
+    /** radio 标识；该 radio 选中时，radio-group 的 change 事件会携带其 value */
     value?: string;
-    /**
-     * @description.en Whether it is currently selected can be set to default
-     * @description.zh 当前是否选中，可用来设置默认选中
-     * @default false
-     */
+    /** 当前是否选中，可作默认选中 */
     checked?: boolean;
-    /**
-     * @description.en disabled
-     * @description.zh 是否禁用
-     * @default false
-     */
+    /** 是否禁用 */
     disabled?: boolean;
-    /**
-     * @description.en color
-     * @description.zh 颜色
-     * @default '#007AFF'
-     */
+    /** radio 的颜色，同 CSS 的 color */
     color?: string;
 }
+/**
+ * Radio 组件文档用默认值（与运行时 defaultProps 分离）
+ *
+ * @belong Radio
+ * @defaults
+ */
+export declare const radioDefaultProps: {
+    checked: boolean;
+    disabled: boolean;
+    color: string;
+};

package/lib/Radio/props.js

@@ -1 +1,22 @@
-export {};
+/**
+ * 单选框，用于在一组互斥选项中选中其中一项。
+ *
+ * @public
+ * @alias Radio
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ *
+ * @example 不同状态 ./demos/states/index.tsx sandbox ide e2e
+ */
+
+/**
+ * Radio 组件文档用默认值（与运行时 defaultProps 分离）
+ *
+ * @belong Radio
+ * @defaults
+ */
+export const radioDefaultProps = {
+  checked: false,
+  disabled: false,
+  color: '#007AFF'
+};

package/lib/RadioGroup/props.d.ts

@@ -1,37 +1,69 @@
+import * as React from 'react';
 import { BaseProps } from '../types';
 import { RadioProps } from '../Radio/props';
-import { GenericEvent } from '@ray-js/adapter';
+import { BaseEvent } from '@ray-js/adapter';
+/** radio-group change 事件数据 */
+export interface RadioGroupChangeDetail {
+    /** 选中项的值 */
+    value: string;
+}
+/** radio-group change 事件对象 */
+export interface RadioGroupChangeEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'change';
+    /** 事件数据 */
+    detail: RadioGroupChangeDetail;
+}
+/**
+ * RadioGroup 选项数据。
+ * 继承 `RadioProps` 的全部属性（如 `value`、`checked`、`disabled`、`color` 等），并额外要求 `label` 作为展示文本。
+ */
 export type RadioGroupOption = RadioProps & {
+    /** 选项标签文本 */
     label: string;
 };
+/** 以 `options` 数据驱动的 RadioGroup（与 children 二选一） */
 export interface IRadioGroupWithOptions {
+    /** 选项列表 */
     options: RadioGroupOption[];
     children?: undefined;
 }
+/** 以 children（`Radio` 子节点）渲染的 RadioGroup（与 options 二选一） */
 export interface IRadioGroupWithChildren {
     options?: undefined;
+    /** 子节点，通常为多个 `Radio` */
     children: React.ReactNode | React.ReactNode[] | string;
 }
-export type RadioGroupProps = (IRadioGroupWithOptions & BaseRadioGroupProps) | (IRadioGroupWithChildren & BaseRadioGroupProps);
+/** RadioGroup 公共属性 */
 export interface BaseRadioGroupProps extends Omit<BaseProps, 'children'> {
-    /**
-     * @description.en name
-     * @description.zh 姓名
-     * @default undefined
-     */
+    /** 表单控件名称，提交表单时作为键名 */
     name?: string;
-    /**
-     * @description.en disabled
-     * @description.zh 是否禁用
-     * @default false
-     */
+    /** 是否禁用 */
     disabled?: boolean;
-    /**
-     * @description.en onChange
-     * @description.zh 选中项发生改变时触发 change 事件
-     * @default undefined
-     */
-    onChange?: (event: GenericEvent<{
-        value: any;
-    }>) => void;
+    /** 选中项发生改变时触发 */
+    onChange?: (event: RadioGroupChangeEvent) => void;
 }
+/**
+ * 单选选择器组，由多个 Radio 组成。`options` 与 children 二选一。
+ *
+ * @public
+ * @alias RadioGroup
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example options 数据驱动 ./demos/options-data/index.tsx sandbox ide e2e
+ */
+export interface RadioGroupProps extends BaseRadioGroupProps {
+    /** 选项列表，与 children 二选一 */
+    options?: RadioGroupOption[];
+    /** 子节点，通常为多个 `Radio`，与 options 二选一 */
+    children?: React.ReactNode | React.ReactNode[] | string;
+}
+/**
+ * RadioGroup 组件默认值
+ *
+ * @belong RadioGroup
+ * @defaults
+ */
+export declare const radioGroupDefaultProps: {
+    disabled: boolean;
+};

package/lib/RadioGroup/props.js

@@ -1 +1,34 @@
-export {};
+/** radio-group change 事件数据 */
+
+/** radio-group change 事件对象 */
+
+/**
+ * RadioGroup 选项数据。
+ * 继承 `RadioProps` 的全部属性（如 `value`、`checked`、`disabled`、`color` 等），并额外要求 `label` 作为展示文本。
+ */
+
+/** 以 `options` 数据驱动的 RadioGroup（与 children 二选一） */
+
+/** 以 children（`Radio` 子节点）渲染的 RadioGroup（与 options 二选一） */
+
+/** RadioGroup 公共属性 */
+
+/**
+ * 单选选择器组，由多个 Radio 组成。`options` 与 children 二选一。
+ *
+ * @public
+ * @alias RadioGroup
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example options 数据驱动 ./demos/options-data/index.tsx sandbox ide e2e
+ */
+
+/**
+ * RadioGroup 组件默认值
+ *
+ * @belong RadioGroup
+ * @defaults
+ */
+export const radioGroupDefaultProps = {
+  disabled: false
+};