@ray-js/components 1.7.78 → 1.7.80

package/lib/Slider/props.d.ts

@@ -1,91 +1,71 @@
-import { GenericEvent } from '@ray-js/adapter';
 import { BaseProps } from '../types';
+import { BaseEvent } from '@ray-js/adapter';
+/** slider 事件数据 */
+export interface SliderEventDetail {
+    /** 当前取值 */
+    value: number;
+}
+/** slider change 事件对象 */
+export interface SliderChangeEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'change';
+    /** 事件数据 */
+    detail: SliderEventDetail;
+    /** 当前取值 */
+    value: number;
+}
+/** slider changing 事件对象 */
+export interface SliderChangingEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'changing';
+    /** 事件数据 */
+    detail: SliderEventDetail;
+    /** 当前取值 */
+    value: number;
+}
+/**
+ * 滑动选择器，通过拖动滑块在数值区间内选取结果。
+ *
+ * @public
+ * @alias Slider
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ *
+ * @example 自定义样式 ./demos/custom-style/index.tsx sandbox ide e2e
+ * @example 禁用与拖动事件 ./demos/disabled-drag/index.tsx sandbox ide e2e
+ */
 export interface SliderProps extends BaseProps {
-    /**
-     * @description.en min
-     * @description.zh 最小值
-     * @default 0
-     */
+    /** 最小值 */
     min?: number;
-    /**
-     * @description.en max
-     * @description.zh 最大值
-     * @default 100
-     */
+    /** 最大值 */
     max?: number;
-    /**
-     * @description.en The value must be greater than 0 and divisible by (max-min)
-     * @description.zh 步长，取值必须大于 0，并且可被(max - min)整除
-     * @default 1
-     */
+    /** 步长，取值必须大于 0，并且可被 (max - min) 整除 */
     step?: number;
-    /**
-     * @description.en disabled
-     * @description.zh 是否禁用
-     * @default false
-     */
+    /** 是否禁用 */
     disabled?: boolean;
-    /**
-     * @description.en value
-     * @description.zh 当前取值
-     * @default 0
-     */
+    /** 当前取值 */
     value?: number;
-    /**
-     * @description.en activeColor
-     * @description.zh 已选择的颜色
-     * @default #007aff
-     */
+    /** 已选择的颜色 */
     activeColor?: string;
-    /**
-     * @description.en backgroundColor
-     * @description.zh 背景条的颜色
-     * @default rgba(0,0,0,.2)
-     */
+    /** 背景条的颜色 */
     backgroundColor?: string;
-    /**
-     * @description.en blockSize
-     * @description.zh 滑块的大小，取值范围为 12 - 28
-     * @default 28
-     */
+    /** 滑块的大小，取值范围为 12～28 */
     blockSize?: number;
-    /**
-     * @description.en blockColor
-     * @description.zh 滑块的颜色
-     * @default #ffffff
-     */
+    /** 滑块的颜色 */
     blockColor?: string;
-    /**
-     * @description.en showValue
-     * @description.zh 是否显示当前 value
-     * @default false
-     */
+    /** 是否显示当前 value */
     showValue?: boolean;
-    /**
-     * @description.en onChange
-     * @description.zh 完成一次拖动后触发的事件，event.detail = {value}
-     * @default undefined
-     */
-    onChange?: (event: GenericEvent<{
-        value: any;
-    }>) => void;
-    /**
-     * @description.en onChanging
-     * @description.zh 拖动过程中触发的事件，event.detail = {value}
-     * @default undefined
-     */
-    onChanging?: (event: GenericEvent<{
-        value: any;
-    }>) => void;
+    /** 表单控件名称，提交表单时作为键名 */
+    name?: string;
+    /** 完成一次拖动后触发 */
+    onChange?: (event: SliderChangeEvent) => void;
+    /** 拖动过程中触发 */
+    onChanging?: (event: SliderChangingEvent) => void;
 }
-export declare const sliderDefault: {
-    blockSize: number;
-    activeColor: string;
-    backgroundColor: string;
-    blockColor: string;
-    min: number;
-    max: number;
-    disabled: boolean;
-    value: number;
-    step: number;
-};
+/**
+ * Slider 组件默认值
+ *
+ * @belong Slider
+ * @defaults
+ */
+export declare const sliderDefault: SliderProps;

package/lib/Slider/props.js

@@ -1,3 +1,27 @@
+/** slider 事件数据 */
+
+/** slider change 事件对象 */
+
+/** slider changing 事件对象 */
+
+/**
+ * 滑动选择器，通过拖动滑块在数值区间内选取结果。
+ *
+ * @public
+ * @alias Slider
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ *
+ * @example 自定义样式 ./demos/custom-style/index.tsx sandbox ide e2e
+ * @example 禁用与拖动事件 ./demos/disabled-drag/index.tsx sandbox ide e2e
+ */
+
+/**
+ * Slider 组件默认值
+ *
+ * @belong Slider
+ * @defaults
+ */
 export const sliderDefault = {
   blockSize: 28,
   activeColor: '#007AFF',
@@ -7,5 +31,6 @@ export const sliderDefault = {
   max: 100,
   disabled: false,
   value: 0,
-  step: 1
+  step: 1,
+  showValue: false
 };

package/lib/Swiper/props.d.ts

@@ -1,181 +1,94 @@
 import * as React from 'react';
 import { BaseProps } from '../types';
-interface Target<T = Record<string, any>> {
-    offsetTop: number;
-    offsetLeft: number;
-    id: string;
-    dataset: T;
+import { BaseEvent } from '@ray-js/adapter';
+/** Swiper 滑块变更事件数据（change 与 afterChange 共用） */
+export interface SwiperChangeDetail {
+    /** 当前滑块索引 */
+    current: number;
+    /** 当前滑块 id */
+    currentItemId?: string;
+    /** 触发原因 */
+    source: '' | 'autoplay' | 'touch';
 }
-export type SwiperProps<I> = BaseProps & {
+/** Swiper current 变更回调事件（components 层） */
+export interface SwiperComponentChangeEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'change';
+    /** 当前滑块索引 */
+    current: number;
+    /** 触发原因 */
+    source: '' | 'autoplay' | 'touch';
+    /** 事件数据 */
+    detail: SwiperChangeDetail;
+}
+/** Swiper 动画结束回调事件（components 层，对应 animationfinish） */
+export interface SwiperComponentAfterChangeEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'afterChange';
+    /** 当前滑块索引 */
+    current: number;
+    /** 触发原因 */
+    source: '' | 'autoplay' | 'touch';
+    /** 事件数据 */
+    detail: SwiperChangeDetail;
+}
+/**
+ * 幻灯片／轮播容器，支持自动切换、衔接滑动与指示点；使用时需明确整体高度。
+ *
+ * @public
+ * @alias Swiper
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ *
+ * @example 自动轮播与 dataSource ./demos/autoplay-datasource/index.tsx sandbox ide e2e
+ * @example 纵向轮播与指示点颜色 ./demos/vertical-dots-color/index.tsx sandbox ide e2e
+ */
+export interface SwiperProps<I = any> extends BaseProps {
     /**
-     * @description.en Whether to display panel points
-     * @description.zh 是否显示面板指示点
-     * @default false
+     * 是否显示面板指示点
      */
     dots?: boolean;
     /**
-     * @description.en Indicator point color
-     * @description.zh 指示点颜色
-     * @default rgba(0, 0, 0, .3)
+     * 指示点颜色
      */
     dotColor?: string;
     /**
-     * @description.en The color of the currently selected indicator point
-     * @description.zh 当前选中的指示点颜色
-     * @default #000000
+     * 当前选中的指示点颜色
      */
     dotActiveColor?: string;
-    /**
-     * @description.en Automatic switch or not
-     * @description.zh 是否自动切换
-     * @default false
-     */
+    /** 是否自动切换 */
     autoplay?: boolean;
-    /**
-     * @description.en Index of the current slider
-     * @description.zh 当前所在滑块的 index
-     * @default 0
-     */
+    /** 当前所在滑块的 index */
     current?: number;
-    /**
-     * @description.en Automatically switch the time interval
-     * @description.zh 自动切换时间间隔
-     * @default 5000
-     */
+    /** 自动切换时间间隔 */
     interval?: number;
-    /**
-     * @description.en Sliding animation duration
-     * @description.zh 滑动动画时长
-     * @default 500
-     */
+    /** 滑动动画时长 */
     duration?: number;
-    /**
-     * @description.en Whether to use cohesive sliding
-     * @description.zh 是否采用衔接滑动
-     * @default false
-     */
+    /** 是否采用衔接滑动 */
     circular?: boolean;
-    /**
-     * @description.en Whether the sliding direction is longitudinal
-     * @description.zh 滑动方向是否为纵向
-     * @default false
-     */
+    /** 滑动方向是否为纵向 */
     vertical?: boolean;
-    /** 前边距，可用于露出前一项的一小部分 */
-    /** 后边距，可用于露出后一项的一小部分 */
     /**
-     * current 改变时会触发 change 事件
-     **/
-    onChange?: (event: {
-        type: 'change';
-        current: number;
-        source: '' | 'autoplay' | 'touch';
-        /**
-         * @description.en Original event object
-         * @description.zh 原始事件对象
-         * @example
-         * {
-         *     "type": "change",
-         *     "timeStamp": 5633,
-         *     "currentTarget": {
-         *         "offsetTop": 12,
-         *         "offsetLeft": 12,
-         *         "id": "",
-         *         "dataset": {
-         *             "a": "b"
-         *         }
-         *     },
-         *     "target": {
-         *         "offsetTop": 12,
-         *         "offsetLeft": 12,
-         *         "id": "",
-         *         "dataset": {
-         *             "a": "b"
-         *         }
-         *     },
-         *     "detail": {
-         *         "current": 2,
-         *         "currentItemId": "",
-         *         "source": "touch"
-         *     }
-         * }
-         */
-        origin?: {
-            type: 'change';
-            timeStamp: number;
-            currentTarget: Target;
-            target: Target;
-            detail: {
-                current: number;
-                currentItemId: string;
-                source: '' | 'autoplay' | 'touch';
-            };
-        };
-        detail: {
-            current: number;
-            source: '' | 'autoplay' | 'touch';
-        };
-    }) => void;
-    /** swiper-item 的位置发生改变时会触发 transition 事件，event.detail = {dx: dx, dy: dy} 2.4.3 */
-    /** 动画结束时会触发 onAfterChange 事件 */
-    onAfterChange?: (event: {
-        type: 'afterChange';
-        current: number;
-        source: '' | 'autoplay' | 'touch';
-        /**
-         * @description.en Original event object
-         * @description.zh 原始事件对象
-         * @example
-         * {
-         *     "type": "animationfinish",
-         *     "timeStamp": 6144,
-         *     "currentTarget": {
-         *         "offsetTop": 12,
-         *         "offsetLeft": 12,
-         *         "id": "",
-         *         "dataset": {
-         *             "a": "b"
-         *         }
-         *     },
-         *     "target": {
-         *         "offsetTop": 12,
-         *         "offsetLeft": 12,
-         *         "id": "",
-         *         "dataset": {
-         *             "a": "b"
-         *         }
-         *     },
-         *     "detail": {
-         *         "current": 2,
-         *         "currentItemId": "",
-         *         "source": "touch"
-         *     }
-         * }
-         */
-        origin?: {
-            type: 'animationfinish';
-            timeStamp: number;
-            currentTarget: Target;
-            target: Target;
-            detail: {
-                current: number;
-                currentItemId: string;
-                source: '' | 'autoplay' | 'touch';
-            };
-        };
-        detail: {
-            value: any;
-        };
-    }) => void;
-    /** 列表数据 */
-    dataSource: I[];
-    /** 渲染列表项目 */
-    renderItem: (item: I, index: number) => React.ReactNode;
-};
-export declare const defaultSwiperProps: Partial<SwiperProps<any>>;
+     * 列表数据，用于与 `renderItem` 组合渲染；泛型 `I` 会推断出每一项的数据类型。
+     * 也可不传 `dataSource`，直接以 `SwiperItem` 作为 children 渲染。
+     */
+    dataSource?: I[];
+    /** 渲染列表每一项，`item` 类型由 `dataSource` 的泛型 `I` 推断 */
+    renderItem?: (item: I, index: number) => React.ReactNode;
+    /** current 改变时触发 */
+    onChange?: (event: SwiperComponentChangeEvent) => void;
+    /** 动画结束时触发 */
+    onAfterChange?: (event: SwiperComponentAfterChangeEvent) => void;
+}
+/**
+ * Swiper 组件默认值
+ *
+ * @belong Swiper
+ * @defaults
+ */
+export declare const defaultSwiperProps: Partial<SwiperProps>;
 export declare const SwiperPropsAlias: {
     dotActiveColor: string;
     dotColor: string;
     dots: string;
 };
-export {};

package/lib/Swiper/props.js

@@ -1,3 +1,27 @@
+/** Swiper 滑块变更事件数据（change 与 afterChange 共用） */
+
+/** Swiper current 变更回调事件（components 层） */
+
+/** Swiper 动画结束回调事件（components 层，对应 animationfinish） */
+
+/**
+ * 幻灯片／轮播容器，支持自动切换、衔接滑动与指示点；使用时需明确整体高度。
+ *
+ * @public
+ * @alias Swiper
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ *
+ * @example 自动轮播与 dataSource ./demos/autoplay-datasource/index.tsx sandbox ide e2e
+ * @example 纵向轮播与指示点颜色 ./demos/vertical-dots-color/index.tsx sandbox ide e2e
+ */
+
+/**
+ * Swiper 组件默认值
+ *
+ * @belong Swiper
+ * @defaults
+ */
 export const defaultSwiperProps = {
   autoplay: false,
   circular: false,

package/lib/SwiperItem/props.d.ts

@@ -1,4 +1,13 @@
+import * as React from 'react';
 import { BaseProps } from '../types';
+/**
+ * 滑块视图容器子项，仅可放置在 Swiper 组件中，宽高自动设置为 100%。
+ *
+ * @public
+ * @alias SwiperItem
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ */
 export interface SwiperItemProps extends BaseProps {
     children?: React.ReactNode | string;
 }

package/lib/Switch/props.d.ts

@@ -1,45 +1,50 @@
-import { GenericEvent } from '@ray-js/adapter';
+import * as React from 'react';
 import { BaseProps } from '../types';
+import { BaseEvent } from '@ray-js/adapter';
+/** switch change 事件数据 */
+export interface SwitchChangeDetail {
+    /** 当前选中状态 */
+    value: boolean;
+}
+/** switch change 事件对象 */
+export interface SwitchChangeEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'change';
+    /** 事件数据，通过 detail.value 获取当前取值 */
+    detail: SwitchChangeDetail;
+}
+/**
+ * 开关选择器，用于在两种互斥状态间切换。
+ *
+ * @public
+ * @alias Switch
+ * @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 SwitchProps extends BaseProps {
-    /**
-     * @description.en onChange
-     * @description.zh checked 改变时触发 change 事件，event.detail={ value}
-     * @default undefined
-     */
-    onChange?: (event: GenericEvent<{
-        value: any;
-    }>) => void;
-    /**
-     * @description.en checked
-     * @description.zh 当前是否选中
-     * @default false
-     */
+    /** 当前是否选中 */
     checked?: boolean;
-    /**
-     * @description.en disabled
-     * @description.zh 是否禁用
-     * @default false
-     */
+    /** 是否禁用 */
     disabled?: boolean;
-    /**
-     * @description.en color
-     * @description.zh Switch 的颜色，同 css 的 color
-     * @default #007AFF
-     */
+    /** 开关颜色，同 CSS 的 color */
     color?: string;
-    /**
-     * @description.en type
-     * @description.zh 可选值 switch checkbox
-     * @default switch
-     */
+    /** 样式类型，可选 switch、checkbox */
     type?: 'switch' | 'checkbox';
-    /**
-     * @description.en style
-     * @description.zh 风格
-     * @default undefined
-     */
+    /** 组件样式 */
     style?: React.CSSProperties;
+    /** 表单控件名称，提交表单时作为键名 */
+    name?: string;
+    /** 选中状态改变时触发，detail 含 value */
+    onChange?: (event: SwitchChangeEvent) => void;
 }
+/**
+ * Switch 组件默认值
+ *
+ * @belong Switch
+ * @defaults
+ */
 export declare const defaultSwitchProps: {
     type: string;
     color: string;

package/lib/Switch/props.js

@@ -1,3 +1,24 @@
+/** switch change 事件数据 */
+
+/** switch change 事件对象 */
+
+/**
+ * 开关选择器，用于在两种互斥状态间切换。
+ *
+ * @public
+ * @alias Switch
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ *
+ * @example 不同状态 ./demos/states/index.tsx sandbox ide e2e
+ */
+
+/**
+ * Switch 组件默认值
+ *
+ * @belong Switch
+ * @defaults
+ */
 export const defaultSwitchProps = {
   type: 'switch',
   color: '#007AFF',

package/lib/Text/props.d.ts

@@ -1,27 +1,38 @@
 import { BaseProps } from '../types';
+/**
+ * 文本内容组件，用于显示文本信息。
+ *
+ * @public
+ * @alias Text
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example 可选择文本 ./demos/selectable/index.tsx sandbox ide e2e
+ */
 export interface TextProps extends BaseProps {
+    /** 文本是否可选 */
+    userSelect?: boolean;
     /**
-     * @description.en selectable
-     * @description.zh 文本是否可选
-     * @default false
+     * 文本是否可选
+     * @deprecated 请使用 `userSelect` 替代
      */
     selectable?: boolean;
-    children?: React.ReactNode;
     /**
-     * @description.en onClick
-     * @description.zh 点击事件
-     * @default false
+     * 是否显示连续的空格
+     * @internal
      */
-    onClick?: (event: {
-        /**
-         * @description.en type
-         * @description.zh 类型
-         * @default undefined
-         */
-        type: string;
-        timeStamp: number;
-        pageX: number;
-        pageY: number;
-        origin: any;
-    }) => void;
+    space?: '' | 'ensp' | 'emsp' | 'nbsp';
+    /**
+     * 是否解码 HTML 字符实体（如 `&`、`<`）
+     * @internal
+     */
+    decode?: boolean;
 }
+/**
+ * Text 组件文档用默认值（与运行时 defaultProps 分离）
+ *
+ * @belong Text
+ * @defaults
+ */
+export declare const textDefaultProps: {
+    userSelect: boolean;
+};

package/lib/Text/props.js

@@ -1 +1,19 @@
-export {};
+/**
+ * 文本内容组件，用于显示文本信息。
+ *
+ * @public
+ * @alias Text
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example 可选择文本 ./demos/selectable/index.tsx sandbox ide e2e
+ */
+
+/**
+ * Text 组件文档用默认值（与运行时 defaultProps 分离）
+ *
+ * @belong Text
+ * @defaults
+ */
+export const textDefaultProps = {
+  userSelect: false
+};