@jari-ace/element-plus-component 0.3.4 → 0.4.1

package/packages/components/dropdownButton/README.md

@@ -0,0 +1,30 @@
+# JaDropdownButton 下拉按钮组件
+
+`JaDropdownButton` 结合了按钮和下拉菜单，支持快捷键和工具提示。
+
+## 组件用途
+
+用于提供一个主按钮和附加的下拉菜单选项。
+
+## 属性 API
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `buttonText` | `string` | - | 按钮显示的文本 |
+| `tooltip` | `string` | - | 按钮的文字提示 |
+| `shortcut` | `string` | - | 快捷键 |
+| `type` | `string` | `'default'` | 按钮类型 |
+| `tooltipPlacement` | `'top' \| 'bottom'` | `'top'` | Tooltip 位置 |
+
+## 使用示例
+
+```vue
+<ja-dropdown-button buttonText="更多操作" type="primary">
+  <template #dropdown>
+    <el-dropdown-menu>
+      <el-dropdown-item>Action 1</el-dropdown-item>
+      <el-dropdown-item>Action 2</el-dropdown-item>
+    </el-dropdown-menu>
+  </template>
+</ja-dropdown-button>
+```

package/packages/components/form/JaForm.vue

@@ -1,32 +1,81 @@
 <script setup lang="ts">
 import {type PropType, provide, ref, computed, watch} from "vue";
 import {ElForm, type FormInstance, type FormRules} from "element-plus";
+import type { FormProps } from "element-plus";
 import {type ValidationInstance} from "../../hooks/useBackendValidations";
 import type {JaFormModel} from "./types";
 import {mergeRules} from '../../utils/formUtils'
-interface Props {
+
+export interface JaFormProps extends Partial<Omit<FormProps, 'model' | 'rules'>> {
+    /**
+     * 表单数据模型
+     */
     model: JaFormModel,
+    /**
+     * 行内表单模式
+     */
     inline?:boolean,
+    /**
+     * 标签位置
+     */
     labelPosition?: "left" | "top" | "right",
+    /**
+     * 标签宽度
+     */
     labelWidth?: string | number,
+    /**
+     * 标签后缀
+     */
     labelSuffix?: string,
+    /**
+     * 隐藏必填星号
+     */
     hideRequiredAsterisk?: boolean,
+    /**
+     * 显示校验错误信息
+     */
     showMessage?: boolean,
+    /**
+     * 以行内形式展示校验信息
+     */
     inlineMessage?: boolean,
+    /**
+     * 显示校验状态图标
+     */
     statusIcon?: boolean,
+    /**
+     * 在规则改变时执行校验
+     */
     validateOnRuleChange?: boolean,
+    /**
+     * 表单验证规则
+     */
     rules?: FormRules,
+    /**
+     * 尺寸
+     */
     size?: "small" | "default" | "large",
+    /**
+     * 是否禁用
+     */
     disabled?: boolean,
+    /**
+     * 滚动到错误项
+     */
     scrollToError?: boolean,
+    /**
+     * 验证器实例
+     */
     validator: ValidationInstance,
+    /**
+     * 必填星号位置
+     */
     requiredPosition?: 'left' | 'right'
 }
 
 const formRef = ref<FormInstance | undefined>(undefined);
 
-
-const props = withDefaults(defineProps<Props>(),{
+const props = withDefaults(defineProps<JaFormProps>(),{
     inline:false,
     labelPosition:'top',
     hideRequiredAsterisk:true,
@@ -39,10 +88,6 @@ const props = withDefaults(defineProps<Props>(),{
     requiredPosition:'right',
 })
 
-
-
-
-
 defineEmits(["validate", "click"]);
 provide("aceFormValidator", props.validator);
 provide("aceFormModel", props.model);
@@ -54,13 +99,11 @@ const model = computed(() => {
     return props.model.formData?props.model.formData:props.model;
 });
 
-
-
 defineExpose({
     elForm: formRef,
     getElForm:():FormInstance|undefined=>formRef.value,
     validate:async (submit: () => Promise<any>, onFail?: () => void) => {
-        if(!formRef)return;
+        if(!formRef.value)return;
         //先清空之前的校验
         formRef.value.clearValidate();
         //判断是否有传入rules如果有则先执行 formRef.value!.validate()
@@ -78,8 +121,8 @@ defineExpose({
                         .catch(() => {
                             //失败
                             //合并rules
-                            rules.value = mergeRules(props.rules, props.validator.rules);
-                            formRef.value.validate();
+                            rules.value = mergeRules(props.rules!, props.validator.rules);
+                            formRef.value!.validate();
                             if (onFail) onFail();
                         });
                 }else{
@@ -94,29 +137,26 @@ defineExpose({
                 .catch(async () => {
                     //失败
                     //合并rules
-                    rules.value = mergeRules(props.rules, props.validator.rules);
-                    await formRef.value.validate();
+                    rules.value = mergeRules(props.rules!, props.validator.rules);
+                    await formRef.value!.validate();
                     if (onFail) onFail();
                 });
         }
-
-
-
     },
     getRules: () => rules.value,
 });
 
-
 watch(() => props.model.formData, () => {
     props.validator?.clearFiledErrors();
 })
 
 watch(() => props.rules, () => {
     //合并rules
-    rules.value = mergeRules(props.rules, props.validator.rules);
+    if (props.rules) {
+        rules.value = mergeRules(props.rules, props.validator.rules);
+    }
 }, { immediate: true })
 
-
 </script>
 
 <template>

package/packages/components/form/README.md

@@ -0,0 +1,30 @@
+# JaForm 表单组件
+
+`JaForm` 是对 Element Plus `ElForm` 的封装，提供了表单数据模型注入和增强的验证功能。
+
+## 组件用途
+
+用于构建表单，管理数据模型和验证规则。
+
+## 属性 API
+
+该组件继承了 [ElForm](https://element-plus.org/zh-CN/component/form.html#form-attributes) 的大部分属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `model` | `JaFormModel` | - | 表单数据模型对象 |
+| `inline` | `boolean` | `false` | 是否为行内表单 |
+| `labelPosition` | `'left' \| 'top' \| 'right'` | `'top'` | 标签位置 |
+| `hideRequiredAsterisk` | `boolean` | `true` | 是否隐藏必填星号（组件内部自行处理） |
+| `validator` | `ValidationInstance` | - | 验证器实例 |
+| `requiredPosition` | `'left' \| 'right'` | `'right'` | 必填星号位置 |
+
+## 使用示例
+
+```vue
+<ja-form :model="formData" :validator="validator">
+  <ja-form-item prop="name" label="Name">
+    <ja-input />
+  </ja-form-item>
+</ja-form>
+```

package/packages/components/formItem/JaFormItem.vue

@@ -1,27 +1,65 @@
 <script setup lang="ts">
 import { provide, ref, withDefaults, defineProps, defineExpose, inject, computed } from "vue";
 import {ElFormItem, ElIcon, ElText, type FormItemRule, ElTooltip} from 'element-plus'
+import type { FormItemProps } from 'element-plus'
 import {QuestionFilled} from "@element-plus/icons-vue";
 
 type RequiredPosition = 'left' | 'right'
 
+const aceFormRequiredPosition = inject('aceFormRequiredPosition') as RequiredPosition | undefined
 
-
-const aceFormRequiredPosition = inject('aceFormRequiredPosition')
-const props = withDefaults(defineProps<{
+export interface JaFormItemProps extends Partial<FormItemProps> {
+    /**
+     * 字段名
+     */
     prop?: string | string[]
+    /**
+     * 验证规则
+     */
     rules?: FormItemRule | FormItemRule[]
+    /**
+     * 标签文本
+     */
     label?: string
+    /**
+     * 标签宽度
+     */
     labelWidth?: string | number
+    /**
+     * 标签说明（Tooltip）
+     */
     labelRemark?: string
+    /**
+     * 是否必填
+     */
     required?: boolean
+    /**
+     * 错误信息
+     */
     error?: string
+    /**
+     * 显示校验信息
+     */
     showMessage?: boolean
+    /**
+     * 行内显示校验信息
+     */
     inlineMessage?: boolean
+    /**
+     * 尺寸
+     */
     size?: 'small' | 'default' | 'large'
+    /**
+     * 必填星号位置
+     */
     requiredPosition?: RequiredPosition
+    /**
+     * 标签间隔
+     */
     labelGap?:string
-}>(), {
+}
+
+const props = withDefaults(defineProps<JaFormItemProps>(), {
     required: false,
     showMessage: true,
     inlineMessage: true,
@@ -35,8 +73,7 @@ const requiredPosition = computed(()=>{
     return props.requiredPosition || aceFormRequiredPosition
 })
 
-
-const formItem = ref<typeof ElFormItem | null>(null)
+const formItem = ref<InstanceType<typeof ElFormItem> | null>(null)
 defineExpose({
     resetField: () => {
         formItem.value!.resetField()
@@ -84,4 +121,3 @@ defineExpose({
         <slot name="error"></slot>
     </el-form-item>
 </template>
-

package/packages/components/formItem/README.md

@@ -0,0 +1,28 @@
+# JaFormItem 表单项组件
+
+`JaFormItem` 是对 Element Plus `ElFormItem` 的封装，增强了标签显示和验证提示。
+
+## 组件用途
+
+用于在 `JaForm` 中包裹表单控件，提供标签、验证错误显示等功能。
+
+## 属性 API
+
+该组件继承了 [ElFormItem](https://element-plus.org/zh-CN/component/form.html#form-item-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `prop` | `string \| string[]` | - | 字段名，对应模型中的路径 |
+| `label` | `string` | - | 标签文本 |
+| `labelRemark` | `string` | - | 标签说明，显示为问号图标和 Tooltip |
+| `required` | `boolean` | `false` | 是否必填 |
+| `labelGap` | `string` | `'4px'` | 标签与说明图标的间距 |
+| `requiredPosition` | `'left' \| 'right'` | - | 必填星号位置（默认跟随 Form 配置） |
+
+## 使用示例
+
+```vue
+<ja-form-item prop="email" label="Email" required labelRemark="请输入公司邮箱">
+  <ja-input />
+</ja-form-item>
+```

package/packages/components/input/JaInput.vue

@@ -1,40 +1,18 @@
 <script setup lang="ts">
-import {type Component, inject, type StyleValue, ref, watch} from 'vue'
+import {type Component, inject, type StyleValue, ref, watch, computed} from 'vue'
 import {ElInput} from 'element-plus'
+import type { InputProps } from 'element-plus'
 import type {ValidationInstance} from '../../hooks/useBackendValidations'
 import type {EpPropMergeType} from "element-plus/es/utils";
 import {getValue, setValue} from "../../utils/objectUtils";
 
-const props = withDefaults(defineProps<{
-    type?: string
-    maxLength?: number
-    minLength?: number
-    showWordLimit?: boolean
-    placeholder?: string
-    clearable?: boolean
-    formatter?: (value: string | number) => string
-    parser?: (value: string) => string
-    showPassword?: boolean
-    disabled?: boolean
-    size?: 'large' | 'default' | 'small'
-    prefixIcon?: string | Component
-    suffixIcon?: string | Component
-    rows?: number
-    autosize?: boolean | object
-    autocomplete?: AutoFill
-    name?: string
-    readonly?: boolean,
-    max?: any
-    min?: any
-    step?: any
-    resize?: 'none' | 'both' | 'horizontal' | 'vertical'
-    autofocus?: boolean
-    form?: string
-    label?: string
-    tabindex?: string | number
-    validateEvent?: boolean
-    inputStyle?: StyleValue
-}>(), {
+export interface JaInputProps extends Partial<InputProps> {
+    // Maintain backward compatibility for props that might differ in case or are custom aliases
+    maxLength?: number | string
+    minLength?: number | string
+}
+
+const props = withDefaults(defineProps<JaInputProps>(), {
     type: 'text',
     showWordLimit: false,
     clearable: false,
@@ -51,13 +29,13 @@ const props = withDefaults(defineProps<{
 const model = inject('aceFormModel') as Record<string, any>
 const prop = inject('aceFormItemProp') as string
 const validator = inject('aceFormValidator') as ValidationInstance
-const input = ref<typeof ElInput>({} as typeof ElInput)
+const input = ref<InstanceType<typeof ElInput>>()
 const emit = defineEmits<{
-    blur: [evt: Event]
-    focus: [evt: Event]
+    blur: [evt: FocusEvent]
+    focus: [evt: FocusEvent]
     change: [value: string]
     input: [value: string]
-    clear: [void]
+    clear: []
 }>()
 
 function onChange(value: string) {
@@ -78,18 +56,30 @@ watch(() => model.formData, () => {
     deep: true
 })
 
+const elementProps = computed(() => {
+    const { modelValue, maxLength, minLength, ...rest } = props
+    // Map maxLength/minLength to maxlength/minlength if needed, or rely on ElInput handling
+    // ElInput expects 'maxlength'. If props has 'maxlength' (from InputProps), use it.
+    // If props has 'maxLength' (custom), map it to 'maxlength' if 'maxlength' is undefined.
+    return {
+        ...rest,
+        maxlength: props.maxlength ?? props.maxLength,
+        minlength: props.minlength ?? props.minLength
+    }
+})
+
 defineExpose({
     focus() {
-        input.value.focus()
+        input.value?.focus()
     },
     blur() {
-        input.value.blur()
+        input.value?.blur()
     },
     select() {
-        input.value.select()
+        input.value?.select()
     },
     clear() {
-        input.value.clear()
+        input.value?.clear()
     },
     elInput: input
 })
@@ -98,34 +88,8 @@ defineExpose({
 <template>
     <el-input
         ref="input"
-        :type="type"
         v-model="mv"
-        :maxlength="maxLength"
-        :minLength="minLength"
-        :show-word-limit="showWordLimit"
-        :placeholder="placeholder"
-        :clearable="clearable"
-        :formatter="formatter"
-        :parser="parser"
-        :show-password="showPassword"
-        :disabled="disabled"
-        :size="size"
-        :prefix-icon="prefixIcon"
-        :suffix-icon="suffixIcon"
-        :rows="rows"
-        :autosize="autosize"
-        :autocomplete="autocomplete"
-        :name="name"
-        :readonly="readonly"
-        :max="max"
-        :min="min"
-        :step="step"
-        :resize="resize"
-        :autofocus="autofocus"
-        :form="form"
-        :label="label"
-        :tabindex="tabindex"
-        :validate-event="validateEvent"
+        v-bind="{ ...elementProps, ...$attrs }"
         @blur="evt => $emit('blur', evt)"
         @focus="evt => $emit('focus', evt)"
         @change="onChange"

package/packages/components/input/README.md

@@ -0,0 +1,23 @@
+# JaInput 输入框组件
+
+`JaInput` 是对 Element Plus `ElInput` 的封装，集成了 `JaForm` 表单上下文注入。
+
+## 组件用途
+
+用于在 `JaForm` 中输入文本，自动绑定数据模型。
+
+## 属性 API
+
+该组件继承了 [ElInput](https://element-plus.org/zh-CN/component/input.html#input-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `maxLength` | `number \| string` | - | `maxlength` 的别名，用于兼容性 |
+| `minLength` | `number \| string` | - | `minlength` 的别名，用于兼容性 |
+| - | - | - | 支持所有 ElInput 属性 |
+
+## 使用示例
+
+```vue
+<ja-input placeholder="Please input" />
+```

package/packages/components/inputNumber/JaInputNumber.vue

@@ -1,29 +1,16 @@
 <script setup lang="ts">
 import {inject, ref, watch, computed} from 'vue'
 import {ElInputNumber} from 'element-plus'
+import type { InputNumberProps } from 'element-plus'
 import type {ValidationInstance} from '../../hooks/useBackendValidations'
 import {getValue, setValue} from "../../utils/objectUtils";
 
 type ModelType = number | null | undefined;
-const props = withDefaults(defineProps<{
-    min?: number
-    max?: number
-    step?: number
-    stepStrictly?: boolean
-    precision?: number
-    size?: 'large' | 'default' | 'small'
-    readonly?: boolean
-    disabled?: boolean
-    controls?: boolean
-    controlsPosition?: '' | 'right'
-    name?: string
-    label?: string
-    ariaLabel?: string
-    placeholder?: string
-    id?: string
-    valueOnClear?: number | null | 'min' | 'max'
-    validateEvent?: boolean
-}>(), {
+
+export interface JaInputNumberProps extends Partial<InputNumberProps> {
+}
+
+const props = withDefaults(defineProps<JaInputNumberProps>(), {
     min: -Infinity,
     max: Infinity,
     step: 1,
@@ -40,10 +27,10 @@ const validator = inject('aceFormValidator') as ValidationInstance
 const size = computed<'large' | 'default' | 'small' | undefined>(() => {
     return props.size ? props.size : inject("aceFormSize");
 });
-const input = ref<typeof ElInputNumber>()
+const input = ref<InstanceType<typeof ElInputNumber>>()
 const emit = defineEmits<{
-    blur: [evt: Event]
-    focus: [evt: Event]
+    blur: [evt: FocusEvent]
+    focus: [evt: FocusEvent]
     change: [value?: ModelType]
 }>()
 
@@ -60,39 +47,32 @@ watch(() => model.formData, () => {
 }, {
     deep: true
 })
+
+const elementProps = computed(() => {
+    const { modelValue, ...rest } = props
+    return rest
+})
+
 defineExpose({
     focus() {
-        input?.value?.focus()
+        input?.value?.focus?.()
     },
     blur() {
-        input?.value?.blur()
+        input?.value?.blur?.()
     },
     elInputNumber: input
 })
 </script>
 
 <template>
-    <el-input-number :min="min"
-                     :max="max"
-                     :label="label"
-                     :disabled="disabled"
-                     :id="id"
-                     :aria-label="ariaLabel"
-                     :controls="controls"
-                     :controls-position="controlsPosition"
-                     v-model.number="mv"
-                     :name="name"
-                     :placeholder="placeholder"
-                     :precision="precision"
-                     :readonly="readonly"
-                     :size="size"
-                     :step="step"
-                     :step-strictly="stepStrictly"
-                     :value-on-clear="valueOnClear"
-                     :validate-event="validateEvent"
-                     @change="onChange"
-                     @blur="evt => $emit('blur', evt)"
-                     @focus="evt => $emit('focus', evt)">
+    <el-input-number
+        ref="input"
+        v-model.number="mv"
+        v-bind="{ ...elementProps, ...$attrs }"
+        :size="size"
+        @change="onChange"
+        @blur="evt => $emit('blur', evt)"
+        @focus="evt => $emit('focus', evt)">
         <slot name="decrease-icon"></slot>
         <slot name="increase-icon"></slot>
     </el-input-number>

package/packages/components/inputNumber/README.md

@@ -0,0 +1,21 @@
+# JaInputNumber 数字输入框组件
+
+`JaInputNumber` 是对 Element Plus `ElInputNumber` 的封装，集成了 `JaForm` 表单上下文注入。
+
+## 组件用途
+
+用于在 `JaForm` 中输入数字，自动绑定数据模型。
+
+## 属性 API
+
+该组件继承了 [ElInputNumber](https://element-plus.org/zh-CN/component/input-number.html#inputnumber-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| - | - | - | 支持所有 ElInputNumber 属性 |
+
+## 使用示例
+
+```vue
+<ja-input-number :min="1" :max="10" />
+```

package/packages/components/radioGroup/JaRadioGroup.vue

@@ -1,11 +1,12 @@
 <script setup lang="ts">
 import type {ValidationInstance} from '../../hooks/useBackendValidations'
-import {inject, ref, watch} from "vue";
+import {inject, ref, watch, computed} from "vue";
 import {ElRadioGroup} from "element-plus";
+import type { RadioGroupProps } from 'element-plus'
 import type {EpPropMergeType} from "element-plus/es/utils";
 import {getValue, setValue} from "../../utils/objectUtils";
 
-const input = ref<typeof ElRadioGroup>({} as typeof ElRadioGroup)
+const input = ref<InstanceType<typeof ElRadioGroup>>()
 const model = inject('aceFormModel') as Record<string, any>
 const prop = inject('aceFormItemProp') as string
 const validator = inject('aceFormValidator') as ValidationInstance
@@ -13,6 +14,11 @@ const emit = defineEmits<{
     change: [value: string | number | boolean | undefined]
 }>()
 
+export interface JaRadioGroupProps extends Partial<RadioGroupProps> {
+}
+
+const props = defineProps<JaRadioGroupProps>()
+
 function onChange(val: string | number | boolean | undefined) {
     validator.removeFieldError(prop)
     setValue(model.formData, prop, mv.value);
@@ -30,9 +36,14 @@ watch(() => model.formData, () => {
     deep: true
 })
 
+const elementProps = computed(() => {
+    const { modelValue, ...rest } = props
+    return rest
+})
+
 defineExpose({
-    focus: () => input.value.focus(),
-    blur: () => input.value.blur(),
+    focus: () => (input.value as any)?.focus?.(), // Optional chaining
+    blur: () => (input.value as any)?.blur?.(), // Check if method exists
     elRadioGroup: input
 })
 </script>
@@ -42,7 +53,7 @@ defineExpose({
         ref="input"
         v-model="mv"
         @change="onChange"
-        v-bind="$attrs">
+        v-bind="{ ...elementProps, ...$attrs }">
         <template v-for="(_, name) in $slots" v-slot:[name]>
             <slot :name="name"></slot>
         </template>