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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jari-ace/element-plus-component",
   "private": false,
-  "version": "0.3.4",
+  "version": "0.4.1",
   "main": "lib/index.umd.cjs",
   "module": "lib/index.js",
   "types": "dist/index.d.ts",

package/packages/components/autoComplete/JaAutoComplete.vue

@@ -1,11 +1,12 @@
 <script setup lang="ts">
-import {ElAutocomplete} from "element-plus";
-import {inject, ref, watch} from "vue";
-import type {ValidationInstance} from "../../hooks/useBackendValidations";
-import type {EpPropMergeType} from "element-plus/es/utils";
-import {getValue, setValue} from "../../utils/objectUtils";
+import { ElAutocomplete } from "element-plus";
+import type { AutocompleteProps } from "element-plus";
+import { inject, ref, watch, computed } from "vue";
+import type { ValidationInstance } from "../../hooks/useBackendValidations";
+import type { EpPropMergeType } from "element-plus/es/utils";
+import { getValue, setValue } from "../../utils/objectUtils";
 
-const input = ref<typeof ElAutocomplete>()
+const input = ref<InstanceType<typeof ElAutocomplete>>()
 const model = inject('aceFormModel') as Record<string, any>
 const prop = inject('aceFormItemProp') as string
 const validator = inject('aceFormValidator') as ValidationInstance
@@ -19,8 +20,7 @@ function onChange(value: string) {
     emit('change', value)
 }
 
-type modelType =
-    EpPropMergeType<readonly [StringConstructor, NumberConstructor], unknown, unknown> | undefined;
+type modelType = EpPropMergeType<readonly [StringConstructor, NumberConstructor], unknown, unknown> | undefined;
 
 const mv = ref(getValue(model.formData, prop) as modelType);
 watch(() => model.formData, () => {
@@ -32,6 +32,16 @@ defineExpose({
     elAutocomplete: input
 })
 
+export interface JaAutoCompleteProps extends Partial<AutocompleteProps> {
+    // Custom props can be added here if needed
+}
+
+const props = defineProps<JaAutoCompleteProps>()
+
+const elementProps = computed(() => {
+    return props
+})
+
 </script>
 
 <template>
@@ -39,7 +49,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>

package/packages/components/autoComplete/README.md

@@ -0,0 +1,35 @@
+# JaAutoComplete 自动补全组件
+
+`JaAutoComplete` 是对 Element Plus `ElAutocomplete` 的封装，集成了表单上下文注入和验证功能。
+
+## 组件用途
+
+主要用于在 `JaForm` 表单中使用，自动绑定表单数据模型和验证规则。
+
+## 属性 API
+
+该组件继承了 [ElAutocomplete](https://element-plus.org/zh-CN/component/autocomplete.html#autocomplete-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| - | - | - | 支持所有 ElAutocomplete 属性 |
+
+## 使用示例
+
+```vue
+<template>
+  <ja-form :model="formData">
+    <ja-form-item prop="city" label="城市">
+      <ja-auto-complete 
+        :fetch-suggestions="querySearch"
+        placeholder="请输入城市"
+      />
+    </ja-form-item>
+  </ja-form>
+</template>
+```
+
+## 注意事项
+
+- 该组件设计为在 `JaForm` 内部使用，依赖 `aceFormModel` 等注入。
+- 自动处理 `v-model` 绑定，无需手动传入 `v-model`，只需确保在 `JaFormItem` 中指定 `prop`。

package/packages/components/avatar/JaAvatar.vue

@@ -1,18 +1,18 @@
 <script setup lang="ts">
-import {getAvatarToken} from "./avatarToken";
-import {ElAvatar, ElImage} from "element-plus";
+import { getAvatarToken } from "./avatarToken";
+import { ElAvatar, ElImage } from "element-plus";
+import type { AvatarProps } from "element-plus";
 import {
     computed,
-    defineProps,
     nextTick,
     onMounted, onUnmounted,
     ref,
     watch,
     withDefaults
 } from "vue";
-import {defaultImg} from "./defaultImg";
+import { defaultImg } from "./defaultImg";
 
-const props = withDefaults(defineProps<{
+export interface JaAvatarProps extends Partial<AvatarProps> {
     /**
      * 用户id
      */
@@ -35,7 +35,9 @@ const props = withDefaults(defineProps<{
     hasAvatar?: boolean,
 
     firstName?: string
-}>(), {
+}
+
+const props = withDefaults(defineProps<JaAvatarProps>(), {
     doNotLoadAvatar: false
 })
 
@@ -51,6 +53,7 @@ if (!scrollbarWrappedItems) {
 onMounted(async () => {
     await nextTick();
     if (scrollbarWrappedItems) {
+        // @ts-ignore
         scrollbarWrappedItems.value?.push({
             childElement: avatar.value?.$el,
             onInView(isInView: boolean) {
@@ -91,15 +94,21 @@ function adjustFontSize(element?: HTMLElement) {
 
 onUnmounted(() => {
     if (scrollbarWrappedItems) {
+        // @ts-ignore
         scrollbarWrappedItems.value = undefined;
     }
 })
 
 watch(usernameSpan, () => adjustFontSize(usernameSpan.value))
+
+const elementProps = computed(() => {
+    const { userId, username, realm, doNotLoadAvatar, hasAvatar, firstName, ...rest } = props
+    return rest
+})
 </script>
 
 <template>
-    <el-avatar :src="lazyUrl" v-bind="$attrs" ref="avatar" class="ja-avatar">
+    <el-avatar :src="lazyUrl" v-bind="{ ...elementProps, ...$attrs }" ref="avatar" class="ja-avatar">
         <span v-if="props.firstName && props.firstName.length > 0" class="user-name-avatar"
               ref="usernameSpan">
             {{ firstName }}

package/packages/components/avatar/README.md

@@ -0,0 +1,45 @@
+# JaAvatar 头像组件
+
+`JaAvatar` 是对 Element Plus `ElAvatar` 的扩展，支持根据用户信息自动加载头像，支持显示用户首字母。
+
+## 组件用途
+
+用于显示用户头像，支持通过 userId 或 username/realm 自动获取头像图片，并在加载失败或无头像时显示默认图片或首字母。
+
+## 属性 API
+
+该组件继承了 [ElAvatar](https://element-plus.org/zh-CN/component/avatar.html#avatar-attributes) 的所有属性，并额外支持以下属性：
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `userId` | `string` | - | 用户 ID，用于构建头像 URL |
+| `username` | `string` | - | 用户名，用于构建头像 URL（需配合 realm） |
+| `realm` | `string` | - | 用户域，用于构建头像 URL |
+| `firstName` | `string` | - | 用户首名，当无头像图片时显示此文字 |
+| `hasAvatar` | `boolean` | - | 用户是否设置了头像 |
+| `doNotLoadAvatar` | `boolean` | `false` | 是否强制不加载头像图片（仅显示 Tag 模式时使用） |
+
+## 使用示例
+
+```vue
+<template>
+  <!-- 通过 User ID 加载 -->
+  <ja-avatar :userId="user.id" :hasAvatar="true" />
+
+  <!-- 显示首字母 -->
+  <ja-avatar firstName="John" />
+  
+  <!-- 完整信息 -->
+  <ja-avatar 
+    :userId="user.id"
+    :firstName="user.firstName"
+    :hasAvatar="user.hasAvatar"
+    size="large"
+  />
+</template>
+```
+
+## 注意事项
+
+- 组件内置了懒加载逻辑，只有当头像进入视图区域时才开始加载图片。
+- 自动处理开发环境 (`isDevMode`) 下的代理路径。

package/packages/components/button/JaButton.vue

@@ -1,21 +1,41 @@
 <script setup lang="ts">
 import dShortcut from "../../directives/shortcut";
 import vAuth from "../../directives/auth";
-import {ElButton, ElTooltip} from "element-plus";
-import {ref} from "vue";
+import { ElButton, ElTooltip } from "element-plus";
+import type { ButtonProps } from "element-plus";
+import { ref, computed } from "vue";
+
+const input = ref<InstanceType<typeof ElButton>>()
 
-const input = ref<typeof ElButton>({} as typeof ElButton)
 type AuthModifier = {
     disable: boolean;
     any: boolean
 }
-const props = withDefaults(defineProps<{
+
+export interface JaButtonProps extends Partial<ButtonProps> {
+    /**
+     * 按钮文字提示
+     */
     tooltip?: string
+    /**
+     * 快捷键
+     */
     shortcut?: string
+    /**
+     * 权限标识
+     */
     auth?: string | string[]
+    /**
+     * 权限修饰符
+     */
     authModifiers?: AuthModifier
+    /**
+     * 提示位置
+     */
     tooltipPlacement?: 'top' | 'bottom'
-}>(), {
+}
+
+const props = withDefaults(defineProps<JaButtonProps>(), {
     tooltipPlacement: 'bottom',
     authModifiers: () => ({
         disable: true,
@@ -25,6 +45,11 @@ const props = withDefaults(defineProps<{
 
 const vShortcut = dShortcut
 
+const elementProps = computed(() => {
+    const { tooltip, shortcut, auth, authModifiers, tooltipPlacement, ...rest } = props
+    return rest
+})
+
 defineExpose({
     elButton: input
 })
@@ -32,12 +57,12 @@ defineExpose({
 </script>
 
 <template>
-    <el-tooltip :placement="tooltipPlacement" append-to="body">
+    <el-tooltip :placement="tooltipPlacement" append-to="body" :disabled="!tooltip && !shortcut">
         <el-button
             ref="input"
             v-auth:[authModifiers]="auth"
             v-shortcut:[shortcut]
-            v-bind="$attrs">
+            v-bind="{ ...elementProps, ...$attrs }">
             <template v-for="(_, name) in $slots" v-slot:[name]>
                 <slot :name="name"></slot>
             </template>

package/packages/components/button/README.md

@@ -0,0 +1,57 @@
+# JaButton 按钮组件
+
+`JaButton` 是对 Element Plus `ElButton` 的扩展封装，增加了工具提示、快捷键绑定和权限控制功能。
+
+## 组件用途
+
+用于在页面中执行操作，支持通过配置快速添加 Tooltip 提示和键盘快捷键，同时集成了权限指令。
+
+## 属性 API
+
+该组件继承了 [ElButton](https://element-plus.org/zh-CN/component/button.html#button-attributes) 的所有属性，并额外支持以下属性：
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `tooltip` | `string` | - | 按钮的文字提示内容 |
+| `shortcut` | `string` | - | 绑定的快捷键（如 'Ctrl+S'） |
+| `auth` | `string \| string[]` | - | 权限标识，用于控制按钮显示/禁用 |
+| `authModifiers` | `AuthModifier` | `{ disable: true, any: false }` | 权限修饰符，`disable`为真时无权限禁用而非隐藏 |
+| `tooltipPlacement` | `'top' \| 'bottom'` | `'bottom'` | Tooltip 提示出现的位置 |
+
+### AuthModifier 类型定义
+```typescript
+type AuthModifier = {
+    disable: boolean;
+    any: boolean
+}
+```
+
+## 使用示例
+
+```vue
+<template>
+  <ja-button 
+    type="primary" 
+    tooltip="保存当前更改" 
+    shortcut="Ctrl+S" 
+    @click="handleSave"
+  >
+    保存
+  </ja-button>
+
+  <ja-button 
+    type="danger" 
+    auth="user:delete"
+    :authModifiers="{ disable: true }"
+    @click="handleDelete"
+  >
+    删除用户
+  </ja-button>
+</template>
+```
+
+## 注意事项
+
+- 当设置了 `tooltip` 或 `shortcut` 时，组件会自动包裹 `ElTooltip`。
+- `shortcut` 需要配合 `v-shortcut` 指令工作（组件内部已集成）。
+- 所有未显式定义的属性将透传给内部的 `ElButton`。

package/packages/components/checkbox/JaCheckbox.vue

@@ -1,23 +1,16 @@
 <script setup lang="ts">
-import {inject, ref, watch} from 'vue'
+import {inject, ref, watch, computed} from 'vue'
 import {type CheckboxValueType, ElCheckbox} from 'element-plus'
+import type { CheckboxProps } from 'element-plus'
 import type {ValidationInstance} from '../../hooks/useBackendValidations'
 import {getValue, setValue} from "../../utils/objectUtils";
 
-const props = withDefaults(defineProps<{
-    label?: string | number | boolean | object
-    trueLabel?: string | number
-    falseLabel?: string | number
-    disabled?: boolean
-    border?: boolean
-    size?: 'large' | 'default' | 'small'
-    name?: string
-    checked?: boolean
-    indeterminate?: boolean
-    validateEvent?: boolean
-}>(), {
+export interface JaCheckboxProps extends Partial<CheckboxProps> {
+    // Custom props or overrides if any
+}
+
+const props = withDefaults(defineProps<JaCheckboxProps>(), {
     disabled: false,
-    border: false,
     checked: false,
     indeterminate: false,
     validateEvent: true
@@ -26,7 +19,7 @@ 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 checkbox = ref<typeof ElCheckbox>({} as typeof ElCheckbox)
+const checkbox = ref<InstanceType<typeof ElCheckbox>>()
 const emit = defineEmits<{
     change: [value: CheckboxValueType]
 }>()
@@ -43,6 +36,12 @@ const mv = ref(getValue(model.formData, prop) as ModelType);
 watch(() => model.formData, () => {
     mv.value = getValue(model.formData, prop) as ModelType
 })
+
+const elementProps = computed(() => {
+    const { modelValue, ...rest } = props
+    return rest
+})
+
 defineExpose({
     elCheckbox: checkbox
 })
@@ -52,17 +51,8 @@ defineExpose({
     <el-checkbox
         ref="checkbox"
         v-model="mv"
-        :disabled="disabled"
-        :true-label="trueLabel"
-        :false-label="falseLabel"
-        :border="border"
-        :size="size"
-        :name="name"
-        :checked="checked"
-        :indeterminate="indeterminate"
-        :validate-event="validateEvent"
-        :label="label"
         @change="onChange"
+        v-bind="{ ...elementProps, ...$attrs }"
     >
         <slot></slot>
     </el-checkbox>

package/packages/components/checkbox/README.md

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

package/packages/components/checkboxGroup/JaCheckboxGroup.vue

@@ -1,10 +1,11 @@
 <script setup lang="ts">
 import type {ValidationInstance} from '../../hooks/useBackendValidations'
-import {inject, ref, watch} from "vue";
+import {inject, ref, watch, computed} from "vue";
 import {type CheckboxGroupValueType, ElCheckboxGroup} from "element-plus";
+import type { CheckboxGroupProps } from 'element-plus'
 import {getValue, setValue} from "../../utils/objectUtils";
 
-const input = ref<typeof ElCheckboxGroup>({} as typeof ElCheckboxGroup)
+const input = ref<InstanceType<typeof ElCheckboxGroup>>()
 const model = inject('aceFormModel') as Record<string, never>
 const prop = inject('aceFormItemProp') as string
 const validator = inject('aceFormValidator') as ValidationInstance
@@ -12,6 +13,11 @@ const emit = defineEmits<{
     change: [value: CheckboxGroupValueType]
 }>()
 
+export interface JaCheckboxGroupProps extends Partial<CheckboxGroupProps> {
+}
+
+const props = defineProps<JaCheckboxGroupProps>()
+
 function onChange(val: CheckboxGroupValueType) {
     validator.removeFieldError(prop)
     setValue(model.formData, prop, mv.value);
@@ -25,9 +31,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 in case ref is not ready or method missing
+    blur: () => (input.value as any)?.blur?.(), // CheckboxGroup might not expose blur directly on type, but runtime it might
     elCheckboxGroup: input
 })
 </script>
@@ -37,7 +48,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>

package/packages/components/checkboxGroup/README.md

@@ -0,0 +1,24 @@
+# JaCheckboxGroup 复选框组组件
+
+`JaCheckboxGroup` 是对 Element Plus `ElCheckboxGroup` 的封装，集成了 `JaForm` 表单上下文注入。
+
+## 组件用途
+
+用于在 `JaForm` 中创建复选框组，自动绑定数据模型。
+
+## 属性 API
+
+该组件继承了 [ElCheckboxGroup](https://element-plus.org/zh-CN/component/checkbox.html#checkboxgroup-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| - | - | - | 支持所有 ElCheckboxGroup 属性 |
+
+## 使用示例
+
+```vue
+<ja-checkbox-group>
+  <ja-checkbox label="Option A" />
+  <ja-checkbox label="Option B" />
+</ja-checkbox-group>
+```

package/packages/components/datePicker/JaDatePicker.vue

@@ -1,26 +1,32 @@
 <script setup lang="ts">
 import type {ValidationInstance} from '../../hooks/useBackendValidations'
-import {inject, onMounted, ref, watch} from "vue";
+import {inject, onMounted, ref, watch, computed} from "vue";
 import {ElDatePicker} from "element-plus";
+import type { DatePickerProps } from "element-plus";
 import {getValue, setValue} from "../../utils/objectUtils";
 
-const input = ref<typeof ElDatePicker>({} as typeof ElDatePicker)
+const input = ref<InstanceType<typeof ElDatePicker>>()
 const model = inject('aceFormModel') as Record<string, any>
 const prop = inject('aceFormItemProp') as string
 const validator = inject('aceFormValidator') as ValidationInstance
 const emit = defineEmits<{
-    change: [value: string]
+    change: [value: any] // DatePicker change value can be Date | string | number | array
 }>()
 
+export interface JaDatePickerProps extends Partial<DatePickerProps> {
+}
+
+const props = defineProps<JaDatePickerProps>()
+
 const exposeMethods = ref<any>({})
 
-function onChange(value: string) {
+function onChange(value: any) {
     validator.removeFieldError(prop);
     setValue(model.formData, prop, mv.value);
     emit('change', value);
 }
 
-type ModelType = string | number | object;
+type ModelType = string | number | object | any;
 
 const mv = ref(getValue(model.formData, prop) as ModelType);
 watch(() => model.formData, () => {
@@ -29,11 +35,18 @@ watch(() => model.formData, () => {
     deep: true
 })
 
+const elementProps = computed(() => {
+    const { modelValue, ...rest } = props
+    return rest
+})
+
 onMounted(() => {
-    const refMethods = Object.entries(input.value).filter(([_, v]) => v instanceof Function);
-    refMethods.forEach(([key, val]) => {
-        exposeMethods.value[key] = val;
-    })
+    if (input.value) {
+        const refMethods = Object.entries(input.value).filter(([_, v]) => v instanceof Function);
+        refMethods.forEach(([key, val]) => {
+            exposeMethods.value[key] = val;
+        })
+    }
 })
 
 defineExpose(exposeMethods.value);
@@ -44,7 +57,7 @@ defineExpose(exposeMethods.value);
         ref="input"
         v-model="model.formData[prop]"
         @change="onChange"
-        v-bind="$attrs">
+        v-bind="{ ...elementProps, ...$attrs }">
         <template v-for="(_, name) in $slots" v-slot:[name]>
             <slot :name="name"></slot>
         </template>

package/packages/components/datePicker/README.md

@@ -0,0 +1,21 @@
+# JaDatePicker 日期选择器组件
+
+`JaDatePicker` 是对 Element Plus `ElDatePicker` 的封装，集成了 `JaForm` 表单上下文注入。
+
+## 组件用途
+
+用于在 `JaForm` 中选择日期，自动绑定数据模型。
+
+## 属性 API
+
+该组件继承了 [ElDatePicker](https://element-plus.org/zh-CN/component/date-picker.html#datepicker-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| - | - | - | 支持所有 ElDatePicker 属性 |
+
+## 使用示例
+
+```vue
+<ja-date-picker type="date" placeholder="Pick a day" />
+```

package/packages/components/dropdownButton/JaDropdownButton.vue

@@ -1,18 +1,36 @@
 <script setup lang="ts">
 import dShortcut from "../../directives/shortcut";
 import {ElButton, ElTooltip, ElDropdown, ElIcon} from "element-plus";
-import {ref} from "vue";
+import {ref, withDefaults, defineProps} from "vue";
 import {ArrowDown} from "@element-plus/icons-vue";
 
-const input = ref<typeof ElButton>()
-const dropdown = ref<typeof ElDropdown>()
-const props = withDefaults(defineProps<{
+const input = ref<InstanceType<typeof ElButton>>()
+const dropdown = ref<InstanceType<typeof ElDropdown>>()
+
+export interface JaDropdownButtonProps {
+    /**
+     * 按钮提示
+     */
     tooltip?: string
+    /**
+     * 快捷键
+     */
     shortcut?: string
+    /**
+     * 按钮文本
+     */
     buttonText?: string
+    /**
+     * 提示位置
+     */
     tooltipPlacement?: 'top' | 'bottom'
+    /**
+     * 按钮类型
+     */
     type?: "default" | "success" | "warning" | "info" | "text" | "primary" | "danger"
-}>(), {
+}
+
+const props = withDefaults(defineProps<JaDropdownButtonProps>(), {
     tooltipPlacement: 'top',
     type: "default"
 })
@@ -30,13 +48,13 @@ function onShortCut(el: HTMLElement) {
 </script>
 
 <template>
-    <el-tooltip :placement="tooltipPlacement">
+    <el-tooltip :placement="tooltipPlacement" :disabled="!tooltip && !shortcut">
         <el-dropdown
             size="default"
             ref="dropdown"
             trigger="click"
             v-bind="$attrs">
-            <el-button ref="input" :type="type" size="default" v-bind="$attrs"
+            <el-button ref="input" :type="type" size="default"
                        v-shortcut:[shortcut]="onShortCut">
                 <template #default>
                     {{ props.buttonText }}