@ray-js/components 1.7.78 → 1.7.80

package/lib/Button/props.d.ts

@@ -1,78 +1,52 @@
+import * as React from 'react';
 import { BaseProps } from '../types';
+/**
+ * 多端按钮基础组件，可用于进行强交互的操作。
+ *
+ * @public
+ * @alias Button
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example 按钮类型 ./demos/type/index.tsx sandbox ide e2e
+ * @example 按钮尺寸 ./demos/size/index.tsx sandbox ide e2e
+ * @example 按钮状态 ./demos/status/index.tsx sandbox ide e2e
+ * @example Hover 点击态与表单 ./demos/hover-form/index.tsx sandbox ide e2e
+ */
 export interface ButtonProps extends BaseProps {
-    /**
-     * @description.en disabled
-     * @description.zh 是否禁用
-     * @default undefined
-     */
-    disabled?: boolean;
-    /**
-     * @description.en loading
-     * @description.zh 是否加载中
-     * @default undefined
-     */
-    loading?: boolean;
-    /**
-     * @description.en Button size
-     * @description.zh 按钮的大小
-     * @default default
-     */
+    /** 按钮的大小 */
     size?: 'default' | 'mini';
-    /**
-     * @description.en The style type of the button
-     * @description.zh 按钮的样式类型
-     * @default default
-     */
+    /** 按钮的样式类型 */
     type?: 'default' | 'primary' | 'warn';
-    /**
-     * @description.en Whether the button hollow, transparent background color
-     * @description.zh 按钮是否镂空，背景色透明
-     * @default undefined
-     */
+    /** 按钮是否镂空，背景色透明 */
     plain?: boolean;
-    /**
-     * @description.en Press down on the style
-     * @description.zh 按下去的样式
-     * @default undefined
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 名称前是否带 loading 图标 */
+    loading?: boolean;
+    /** 用于 form 组件，点击分别会触发 form 组件的 submit/reset 事件 */
+    formType?: 'submit' | 'reset';
+    /** 按下去的样式
+     * @internal
      */
-    hoverStyle?: any;
+    hoverStyle?: string | React.CSSProperties;
     /**
-     * @description.en Press down class on the style
-     * @description.zh 按下去的样式class
-     * @default undefined
+     * 指定按钮按下去的样式类
+     * @internal
      */
     hoverClassName?: string;
-    /**
-     * @description.en How long does it take for the click state to appear after holding, in milliseconds
-     * @description.zh 按住后多久出现点击态，单位毫秒
-     * @default undefined
-     */
+    /** 按住后多久出现点击态，单位毫秒 */
     hoverStartTime?: number;
-    /**
-     * @description.en Click retention time after finger release, in milliseconds
-     * @description.zh 手指松开后点击态保留时间，单位毫秒
-     * @default undefined
-     */
+    /** 手指松开后点击态保留时间，单位毫秒 */
     hoverStayTime?: number;
-    /**
-     * @description.en onClick
-     * @description.zh 点击回调
-     * @default undefined
-     */
-    onClick?: (params: {
-        /**
-         * @description.en type
-         * @description.zh 类型
-         * @default undefined
-         */
-        type: 'click';
-    }) => void;
+    /** 子节点 */
     children?: React.ReactNode;
-    /**
-     * @description.en For the Form component, clicking on each of the Form component's Submit /reset events triggers it
-     * @description.zh 用于 form 组件，点击分别会触发 form 组件的 submit/reset 事件
-     * @default undefined
-     */
-    formType?: 'submit' | 'reset';
+    /** 点击按钮时触发 */
+    onClick?: BaseProps['onClick'];
 }
+/**
+ * Button 组件默认值
+ *
+ * @belong Button
+ * @defaults
+ */
 export declare const defaultButtonProps: ButtonProps;

package/lib/Button/props.js

@@ -1,10 +1,31 @@
+/**
+ * 多端按钮基础组件，可用于进行强交互的操作。
+ *
+ * @public
+ * @alias Button
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example 按钮类型 ./demos/type/index.tsx sandbox ide e2e
+ * @example 按钮尺寸 ./demos/size/index.tsx sandbox ide e2e
+ * @example 按钮状态 ./demos/status/index.tsx sandbox ide e2e
+ * @example Hover 点击态与表单 ./demos/hover-form/index.tsx sandbox ide e2e
+ */
+
+/**
+ * Button 组件默认值
+ *
+ * @belong Button
+ * @defaults
+ */
 export const defaultButtonProps = {
   size: 'default',
   type: 'default',
+  plain: false,
+  loading: false,
+  disabled: false,
   hoverStyle: {
     opacity: 0.8
   },
   hoverStartTime: 20,
-  hoverStayTime: 70,
-  disabled: false
+  hoverStayTime: 70
 };

package/lib/Checkbox/props.d.ts

@@ -1,27 +1,32 @@
 import { BaseProps } from '../types';
+/**
+ * 多选框，用于在选项列表中开启或关闭单项选择。
+ *
+ * @public
+ * @alias Checkbox
+ * @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 CheckboxProps extends BaseProps {
-    /**
-     * @description.en If this parameter is selected, the change event of the checkbox-group is triggered and the value of the checkbox is carried
-     * @description.zh checkbox标识，选中时触发checkbox-group的 change 事件，并携带 checkbox 的 value
-     * @default undefined
-     */
+    /** 选中时触发所属 checkbox-group 的 change 事件，并携带该 value */
     value?: string;
-    /**
-     * @description.en Whether it is currently selected can be set to default
-     * @description.zh 当前是否选中，可用来设置默认选中
-     * @default undefined
-     */
+    /** 当前是否选中，可作默认选中 */
     checked?: boolean;
-    /**
-     * @description.en is disabled
-     * @description.zh 是否禁用
-     * @default undefined
-     */
+    /** 是否禁用 */
     disabled?: boolean;
-    /**
-     * @description.en color
-     * @description.zh 颜色
-     * @default undefined
-     */
+    /** 多选框颜色，同 CSS color */
     color?: string;
 }
+/**
+ * Checkbox 组件文档用默认值（与运行时 defaultProps 分离）
+ *
+ * @belong Checkbox
+ * @defaults
+ */
+export declare const checkboxDefaultProps: {
+    disabled: boolean;
+    checked: boolean;
+    color: string;
+};

package/lib/Checkbox/props.js

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

package/lib/CheckboxGroup/props.d.ts

@@ -1,41 +1,69 @@
+import * as React from 'react';
 import { BaseProps } from '../types';
 import { CheckboxProps } from '../Checkbox/props';
-import { GenericEvent } from '@ray-js/adapter';
+import { BaseEvent } from '@ray-js/adapter';
+/** checkbox-group change 事件数据 */
+export interface CheckboxGroupChangeDetail {
+    /** 选中项的值列表 */
+    value: string[];
+}
+/** checkbox-group change 事件对象 */
+export interface CheckboxGroupChangeEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'change';
+    /** 事件数据 */
+    detail: CheckboxGroupChangeDetail;
+}
+/**
+ * CheckboxGroup 选项数据。
+ * 继承 `CheckboxProps` 的全部属性（如 `value`、`checked`、`disabled`、`color` 等），并额外要求 `label` 作为展示文本。
+ */
 export type CheckboxGroupOption = CheckboxProps & {
+    /** 选项标签文本 */
     label: string;
 };
+/** 以 `options` 数据驱动的 CheckboxGroup（与 children 二选一） */
 export interface ICheckboxGroupWithOptions {
+    /** 选项列表 */
     options: CheckboxGroupOption[];
     children?: undefined;
 }
+/** 以 children（`Checkbox` 子节点）渲染的 CheckboxGroup（与 options 二选一） */
 export interface ICheckboxGroupWithChildren {
     options?: undefined;
+    /** 子节点，通常为多个 `Checkbox` */
     children: React.ReactNode | React.ReactNode[] | string;
 }
-export type CheckboxGroupProps = (ICheckboxGroupWithOptions & BaseCheckboxGroupProps) | (ICheckboxGroupWithChildren & BaseCheckboxGroupProps);
+/** CheckboxGroup 公共属性 */
 export interface BaseCheckboxGroupProps extends Omit<BaseProps, 'children'> {
-    /**
-     * @description.en name
-     * @description.zh 姓名
-     * @default undefined
-     */
+    /** 表单控件名称，提交表单时作为键名 */
     name?: string;
-    /**
-     * @description.en disabled
-     * @description.zh 是否禁用
-     * @default null
-     */
+    /** 是否禁用 */
     disabled?: boolean;
-    /**
-     * @description.en Triggered when the selected item is changed
-     * @description.zh 选中项发生改变时触发 change 事件
-     * @default null
-     */
-    onChange?: (event: GenericEvent<{
-        value: any;
-    } & {
-        type: string;
-        value: string[];
-        origin: any;
-    }>) => void;
+    /** 选中项发生改变时触发 */
+    onChange?: (event: CheckboxGroupChangeEvent) => void;
 }
+/**
+ * 多项选择器组，由多个 Checkbox 组成。`options` 与 children 二选一。
+ *
+ * @public
+ * @alias CheckboxGroup
+ * @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 CheckboxGroupProps extends BaseCheckboxGroupProps {
+    /** 选项列表，与 children 二选一 */
+    options?: CheckboxGroupOption[];
+    /** 子节点，通常为多个 `Checkbox`，与 options 二选一 */
+    children?: React.ReactNode | React.ReactNode[] | string;
+}
+/**
+ * CheckboxGroup 组件默认值
+ *
+ * @belong CheckboxGroup
+ * @defaults
+ */
+export declare const checkboxGroupDefaultProps: {
+    disabled: boolean;
+};

package/lib/CheckboxGroup/props.js

@@ -1 +1,34 @@
-export {};
+/** checkbox-group change 事件数据 */
+
+/** checkbox-group change 事件对象 */
+
+/**
+ * CheckboxGroup 选项数据。
+ * 继承 `CheckboxProps` 的全部属性（如 `value`、`checked`、`disabled`、`color` 等），并额外要求 `label` 作为展示文本。
+ */
+
+/** 以 `options` 数据驱动的 CheckboxGroup（与 children 二选一） */
+
+/** 以 children（`Checkbox` 子节点）渲染的 CheckboxGroup（与 options 二选一） */
+
+/** CheckboxGroup 公共属性 */
+
+/**
+ * 多项选择器组，由多个 Checkbox 组成。`options` 与 children 二选一。
+ *
+ * @public
+ * @alias CheckboxGroup
+ * @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
+ */
+
+/**
+ * CheckboxGroup 组件默认值
+ *
+ * @belong CheckboxGroup
+ * @defaults
+ */
+export const checkboxGroupDefaultProps = {
+  disabled: false
+};

package/lib/CoverView/props.d.ts

@@ -1,5 +1,7 @@
+import * as React from 'react';
 import { BaseProps } from '../types';
 export type CoverViewProps = BaseProps & {
-    children?: any;
+    /** 子节点 */
+    children?: React.ReactNode;
 };
 export declare const defaultCoverViewProps: Partial<CoverViewProps>;

package/lib/Form/props.d.ts

@@ -1,23 +1,40 @@
 import { BaseProps } from '../types';
-export type FormProps = BaseProps & {
-    /**
-     * @description.en Trigger the Submit event with the data in the form
-     * @description.zh 携带 form 中的数据触发 submit 事件
-     * @default null
-     */
-    onSubmit?(event: {
-        type: 'form';
-        origin: any;
-        value: any;
-    }): void;
-    /**
-     * @description.en Triggered when the form is reset
-     * @description.zh 表单重置时会触发
-     * @default null
-     */
-    onReset?(event: {
-        type: 'form';
-        origin: any;
-        value: any;
-    }): void;
-};
+import { BaseEvent } from '@ray-js/adapter';
+/** 表单提交事件数据 */
+export interface FormSubmitDetail {
+    /** 表单数据，key 为各表单控件的 name */
+    value: Record<string, unknown>;
+}
+/** 表单提交事件对象 */
+export interface FormSubmitEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'submit';
+    /** 事件数据，通过 detail.value 获取表单数据 */
+    detail: FormSubmitDetail;
+}
+/** 表单重置事件对象 */
+export interface FormResetEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'reset';
+}
+/**
+ * 表单容器，用于收集并提交其内部控件的输入值。
+ *
+ * @public
+ * @alias Form
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ */
+export interface FormProps extends BaseProps {
+    /** 携带 form 中的数据，提交时触发 */
+    onSubmit?: (event: FormSubmitEvent) => void;
+    /** 表单重置时触发 */
+    onReset?: (event: FormResetEvent) => void;
+}
+/**
+ * Form 组件默认值
+ *
+ * @belong Form
+ * @defaults
+ */
+export declare const formDefaultProps: Partial<FormProps>;

package/lib/Form/props.js

@@ -1 +1,22 @@
-export {};
+/** 表单提交事件数据 */
+
+/** 表单提交事件对象 */
+
+/** 表单重置事件对象 */
+
+/**
+ * 表单容器，用于收集并提交其内部控件的输入值。
+ *
+ * @public
+ * @alias Form
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ */
+
+/**
+ * Form 组件默认值
+ *
+ * @belong Form
+ * @defaults
+ */
+export const formDefaultProps = {};

package/lib/Image/props.d.ts

@@ -1 +1,98 @@
-export type { ImageProps } from '@ray-js/adapter';
+import { BaseProps } from '../types';
+import { BaseEvent } from '@ray-js/adapter';
+/** 图片裁剪、缩放模式 */
+export type ImageMode = 
+/** 缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素 */
+'scaleToFill'
+/** 缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来 */
+ | 'aspectFit'
+/** 缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来 */
+ | 'aspectFill'
+/** 缩放模式，宽度不变，高度自动变化，保持原图宽高比不变 */
+ | 'widthFix'
+/** 缩放模式，高度不变，宽度自动变化，保持原图宽高比不变 */
+ | 'heightFix'
+/** 裁剪模式，不缩放图片，只显示图片的顶部区域 */
+ | 'top'
+/** 裁剪模式，不缩放图片，只显示图片的底部区域 */
+ | 'bottom'
+/** 裁剪模式，不缩放图片，只显示图片的中间区域 */
+ | 'center'
+/** 裁剪模式，不缩放图片，只显示图片的左边区域 */
+ | 'left'
+/** 裁剪模式，不缩放图片，只显示图片的右边区域 */
+ | 'right'
+/** 裁剪模式，不缩放图片，只显示图片的左上边区域 */
+ | 'top left'
+/** 裁剪模式，不缩放图片，只显示图片的右上边区域 */
+ | 'top right'
+/** 裁剪模式，不缩放图片，只显示图片的左下边区域 */
+ | 'bottom left'
+/** 裁剪模式，不缩放图片，只显示图片的右下边区域 */
+ | 'bottom right';
+/** 图片加载成功事件数据 */
+export interface ImageLoadDetail {
+    /** 图片宽度，单位 px */
+    width: number;
+    /** 图片高度，单位 px */
+    height: number;
+}
+/** 图片加载成功事件对象 */
+export interface ImageLoadEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'load';
+    /** 事件数据 */
+    detail: ImageLoadDetail;
+}
+/** 图片加载失败事件数据 */
+export interface ImageErrorDetail {
+    /** 错误信息 */
+    errMsg: string;
+}
+/** 图片加载失败事件对象 */
+export interface ImageErrorEvent extends BaseEvent {
+    /** 事件类型 */
+    type: 'error';
+    /** 事件数据 */
+    detail: ImageErrorDetail;
+}
+/**
+ * 图片组件，支持多种裁剪和缩放模式。
+ *
+ * @public
+ * @alias Image
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example 缩放模式 ./demos/mode/index.tsx sandbox ide e2e
+ * @example 懒加载与渐显 ./demos/lazy-fade/index.tsx sandbox ide e2e
+ */
+export interface ImageProps extends BaseProps {
+    /** 图片资源地址 */
+    src?: string;
+    /** 图片裁剪、缩放的模式 */
+    mode?: ImageMode;
+    /**
+     * 默认不解析 WebP，仅部分端支持；仅网络资源
+     * @internal
+     */
+    webp?: boolean;
+    /** 懒加载，进入一定范围后再加载 */
+    lazyLoad?: boolean;
+    /** 加载过程中渐显时长，单位 ms */
+    fadeDuration?: number;
+    /** 加载失败时触发 */
+    onError?: (event: ImageErrorEvent) => void;
+    /** 载入完毕时触发 */
+    onLoad?: (event: ImageLoadEvent) => void;
+}
+/**
+ * Image 组件文档用默认值（与运行时 defaultProps 分离）
+ *
+ * @belong Image
+ * @defaults
+ */
+export declare const imageDefaultProps: {
+    mode: string;
+    lazyLoad: boolean;
+    fadeDuration: number;
+};

package/lib/Image/props.js

@@ -1 +1,32 @@
-export {};
+/** 图片裁剪、缩放模式 */
+
+/** 图片加载成功事件数据 */
+
+/** 图片加载成功事件对象 */
+
+/** 图片加载失败事件数据 */
+
+/** 图片加载失败事件对象 */
+
+/**
+ * 图片组件，支持多种裁剪和缩放模式。
+ *
+ * @public
+ * @alias Image
+ * @since @ray-js/ray 0.5.10
+ * @example 基础用法 ./demos/basic/index.tsx sandbox ide e2e
+ * @example 缩放模式 ./demos/mode/index.tsx sandbox ide e2e
+ * @example 懒加载与渐显 ./demos/lazy-fade/index.tsx sandbox ide e2e
+ */
+
+/**
+ * Image 组件文档用默认值（与运行时 defaultProps 分离）
+ *
+ * @belong Image
+ * @defaults
+ */
+export const imageDefaultProps = {
+  mode: 'scaleToFill',
+  lazyLoad: false,
+  fadeDuration: 0
+};

package/lib/Input/Input.js

@@ -7,6 +7,7 @@ import * as React from 'react';
 import clsx from 'clsx';
 import { useEventListener } from 'ahooks';
 import { inlineStyle, useStylesheet } from '@ray-js/framework-shared';
+import s2o from 'style-to-object';
 import { defaultInputProps } from './props';
 import styles from './index.module.less';
 import handleProps from '../utils/handleProps';
@@ -20,7 +21,8 @@ const Input = /*#__PURE__*/React.forwardRef((props, ref) => {
       onConfirm
     } = props,
     restProps = _objectWithoutProperties(props, _excluded);
-  const [placeholderStyleClassName] = useStylesheet(inlineStyle(placeholderStyle));
+  const placeholderStyleForSheet = placeholderStyle == null ? undefined : typeof placeholderStyle === 'string' ? s2o(placeholderStyle) : placeholderStyle;
+  const [placeholderStyleClassName] = useStylesheet(inlineStyle(placeholderStyleForSheet));
   const currentNode = ref || React.useRef(null);
   useEventListener('focus', e => {
     onFocus === null || onFocus === void 0 || onFocus(_objectSpread(_objectSpread({}, e), {}, {