@scorpioz/suna-components 0.0.2

package/README.md

@@ -0,0 +1,52 @@
+# Suna Components
+
+Vue 3 component library based on [Element Plus](https://element-plus.org/).
+
+- **Button** — action buttons with type/size/loading/icon support
+- **DebounceButton** — click with debounce (trailing or leading)
+- **ConfirmButton** — confirmation popover before executing actions
+- **Drawer** — slide-in panel with configurable direction/size/footer
+- **DrawerForm** — Drawer + Form composition for create/edit flows
+- **Form** — config-driven form (define fields via `formItems` array), with validation, layout grid, detail mode (read-only), and built-in action bar
+
+## Install
+
+```bash
+npm install @scorpioz/suna-components
+# or
+pnpm add @scorpioz/suna-components
+```
+
+Peer dependencies: `vue ^3.5.0`, `element-plus ^2.14.0`.
+
+## Usage
+
+```ts
+import { createApp } from "vue";
+import ElementPlus from "element-plus";
+import { createComponents } from "@scorpioz/suna-components";
+
+const app = createApp(App);
+app.use(ElementPlus);
+app.use(createComponents());
+// Now use <SunaButton>, <SunaForm>, <SunaDrawer>, etc.
+```
+
+Custom prefix:
+
+```ts
+app.use(createComponents({ prefix: "S" }));
+// <SButton>, <SForm>, <SDrawer>, …
+```
+
+## Import Style
+
+Element Plus styles are imported once when you install the components:
+
+```ts
+import "element-plus/dist/index.css"; // already included via createComponents()
+```
+
+## Docs
+
+See the [full documentation](https://github.com/scorpioz/web-component).

package/button/index.ts

@@ -0,0 +1,3 @@
+export { default as Button } from "./src/Button.vue";
+export { default } from "./src/Button.vue";
+export type * from "./src/types";

package/button/src/Button.vue

@@ -0,0 +1,42 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { ElButton } from "element-plus";
+import { buttonProps } from "./props";
+import type { ElButtonType } from "./types";
+
+defineOptions({ name: "SunaButton" });
+
+// props 定义抽取到 ./props（运行时声明 + PropType，原因见该文件）
+const props = defineProps(buttonProps);
+
+const emit = defineEmits<{ click: [evt: MouseEvent] }>();
+
+// Element Plus 的默认 type 为空字符串，将我们的 "default" 映射为 ""
+const elType = computed<ElButtonType>(() =>
+  props.type === "default" ? "" : props.type
+);
+</script>
+
+<template>
+  <!--
+    基于 Element Plus 的 ElButton 封装：
+    - 声明的 props 显式绑定并设置了默认值；
+    - 其余属性（如 icon / tag / autofocus / class / id 等）通过 attrs 自动透传；
+    - 透传 `#icon`、`#loading`、默认插槽。
+  -->
+  <ElButton
+    :type="elType"
+    :size="size"
+    :plain="plain"
+    :round="round"
+    :circle="circle"
+    :disabled="disabled"
+    :loading="loading"
+    :native-type="nativeType"
+    @click="emit('click', $event)"
+  >
+    <template v-if="$slots.icon" #icon><slot name="icon" /></template>
+    <template v-if="$slots.loading" #loading><slot name="loading" /></template>
+    <slot />
+  </ElButton>
+</template>

package/button/src/props.ts

@@ -0,0 +1,24 @@
+import type { PropType } from "vue";
+import type { ButtonType, ButtonSize, NativeButtonType } from "./types";
+
+/**
+ * Button 的运行时 props 声明（从 .vue 中抽出，保持模板文件简洁）。
+ *
+ * 采用运行时声明（而非 defineProps<T>() 类型声明）：@vue/compiler-sfc 在 dev 下解析
+ * defineProps<T>() 时会静态分析类型，无法可靠解析跨文件导入的类型，会抛出
+ * "Unresolvable type reference"。运行时声明配合 PropType 断言既保证类型安全，
+ * 又不触发该解析；抽到独立文件后依然是「值」而非「类型」，同样不受影响。
+ */
+export const buttonProps = {
+  type: { type: String as PropType<ButtonType>, default: "default" },
+  size: { type: String as PropType<ButtonSize>, default: "default" },
+  plain: { type: Boolean, default: false },
+  round: { type: Boolean, default: false },
+  circle: { type: Boolean, default: false },
+  disabled: { type: Boolean, default: false },
+  loading: { type: Boolean, default: false },
+  nativeType: {
+    type: String as PropType<NativeButtonType>,
+    default: "button",
+  },
+};

package/button/src/types.ts

@@ -0,0 +1,26 @@
+/** 按钮类型（对外暴露的 API 类型，default 表示默认样式） */
+export type ButtonType =
+  | "default"
+  | "primary"
+  | "success"
+  | "warning"
+  | "danger"
+  | "info";
+
+/** 按钮尺寸 */
+export type ButtonSize = "large" | "default" | "small";
+
+/** 原生 button 的 type 属性 */
+export type NativeButtonType = "button" | "submit" | "reset";
+
+/**
+ * Element Plus 接受的按钮类型。
+ * EP 的默认类型以空字符串表示，因此需要把我们的 "default" 映射为 ""。
+ */
+export type ElButtonType =
+  | ""
+  | "primary"
+  | "success"
+  | "warning"
+  | "danger"
+  | "info";

package/confirm-button/index.ts

@@ -0,0 +1,2 @@
+export { default as ConfirmButton } from "./src/ConfirmButton.vue";
+export { default } from "./src/ConfirmButton.vue";

package/confirm-button/src/ConfirmButton.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import { ElPopconfirm } from "element-plus";
+import SunaButton from "../../button/src/Button.vue";
+import { confirmButtonProps } from "./props";
+
+defineOptions({ name: "SunaConfirmButton", inheritAttrs: false });
+
+// props 定义抽取到 ./props（运行时声明 + PropType，原因见该文件）
+defineProps(confirmButtonProps);
+
+const emit = defineEmits<{ confirm: []; cancel: [] }>();
+
+const onConfirm = () => emit("confirm");
+const onCancel = () => emit("cancel");
+
+// 显式声明的 props 之外，其余属性（teleported / popper-class / icon / class 等）透传给 ElPopconfirm
+</script>
+
+<template>
+  <ElPopconfirm
+    :title="title"
+    :confirm-button-text="confirmButtonText"
+    :cancel-button-text="cancelButtonText"
+    :confirm-button-type="confirmButtonType"
+    :cancel-button-type="cancelButtonType"
+    :icon-color="iconColor"
+    :hide-icon="hideIcon"
+    :width="width"
+    :placement="placement"
+    :hide-after="hideAfter"
+    :disabled="disabled"
+    v-bind="$attrs"
+    @confirm="onConfirm"
+    @cancel="onCancel"
+  >
+    <template #reference>
+      <SunaButton
+        :type="type"
+        :size="size"
+        :plain="plain"
+        :round="round"
+        :circle="circle"
+        :disabled="disabled"
+        :loading="loading"
+        :native-type="nativeType"
+      >
+        <template v-if="$slots.icon" #icon><slot name="icon" /></template>
+        <slot />
+      </SunaButton>
+    </template>
+  </ElPopconfirm>
+</template>

package/confirm-button/src/props.ts

@@ -0,0 +1,50 @@
+import type { PropType } from "vue";
+import type {
+  ButtonType,
+  ButtonSize,
+  NativeButtonType,
+  ElButtonType,
+} from "../../button/src/types";
+
+/**
+ * ConfirmButton 的 props：触发按钮属性 + 弹层确认属性（运行时声明，见同类文件说明）。
+ */
+export const confirmButtonProps = {
+  // ---- 触发按钮属性 ----
+  type: { type: String as PropType<ButtonType>, default: "primary" },
+  size: { type: String as PropType<ButtonSize>, default: "default" },
+  plain: { type: Boolean, default: false },
+  round: { type: Boolean, default: false },
+  circle: { type: Boolean, default: false },
+  disabled: { type: Boolean, default: false },
+  loading: { type: Boolean, default: false },
+  nativeType: {
+    type: String as PropType<NativeButtonType>,
+    default: "button",
+  },
+
+  // ---- 弹层确认属性 ----
+  /** 确认提示文案 */
+  title: { type: String, default: "确定执行此操作吗？" },
+  /** 确认按钮文字 */
+  confirmButtonText: { type: String, default: "确定" },
+  /** 取消按钮文字 */
+  cancelButtonText: { type: String, default: "取消" },
+  /** 确认按钮类型 */
+  confirmButtonType: {
+    type: String as PropType<ElButtonType>,
+    default: "primary",
+  },
+  /** 取消按钮类型 */
+  cancelButtonType: { type: String as PropType<ElButtonType>, default: "" },
+  /** 图标颜色 */
+  iconColor: { type: String, default: "#e6a23c" },
+  /** 是否隐藏图标 */
+  hideIcon: { type: Boolean, default: false },
+  /** 弹层宽度（px） */
+  width: { type: Number, default: 200 },
+  /** 弹层出现位置 */
+  placement: { type: String, default: "top" },
+  /** 确认/取消后延迟隐藏弹层的时间（ms） */
+  hideAfter: { type: Number, default: 200 },
+};

package/debounce-button/index.ts

@@ -0,0 +1,2 @@
+export { default as DebounceButton } from "./src/DebounceButton.vue";
+export { default } from "./src/DebounceButton.vue";

package/debounce-button/src/DebounceButton.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { onBeforeUnmount } from "vue";
+import SunaButton from "../../button/src/Button.vue";
+import { debounceButtonProps } from "./props";
+
+defineOptions({ name: "SunaDebounceButton" });
+
+// props 定义抽取到 ./props（复用 buttonProps + 防抖参数）
+const props = defineProps(debounceButtonProps);
+
+const emit = defineEmits<{ click: [evt: MouseEvent] }>();
+
+let timer: ReturnType<typeof setTimeout> | null = null;
+let pendingEvt: MouseEvent | null = null;
+
+const clearTimer = () => {
+  if (timer !== null) {
+    clearTimeout(timer);
+    timer = null;
+  }
+};
+
+const handleClick = (evt: MouseEvent) => {
+  if (props.leading) {
+    // 前缘防抖：未锁定时立即触发，随后锁定 wait 毫秒（锁定期内忽略点击）
+    if (timer === null) {
+      emit("click", evt);
+      timer = setTimeout(() => {
+        timer = null;
+      }, props.wait);
+    }
+    return;
+  }
+
+  // 后缘防抖：记录最近一次点击，重置计时，停止点击 wait 毫秒后触发一次
+  pendingEvt = evt;
+  clearTimer();
+  timer = setTimeout(() => {
+    const e = pendingEvt;
+    timer = null;
+    pendingEvt = null;
+    if (e) emit("click", e);
+  }, props.wait);
+};
+
+onBeforeUnmount(clearTimer);
+</script>
+
+<template>
+  <SunaButton
+    :type="type"
+    :size="size"
+    :plain="plain"
+    :round="round"
+    :circle="circle"
+    :disabled="disabled"
+    :loading="loading"
+    :native-type="nativeType"
+    @click="handleClick"
+  >
+    <template v-if="$slots.icon" #icon><slot name="icon" /></template>
+    <template v-if="$slots.loading" #loading><slot name="loading" /></template>
+    <slot />
+  </SunaButton>
+</template>

package/debounce-button/src/props.ts

@@ -0,0 +1,15 @@
+import { buttonProps } from "../../button/src/props";
+
+/**
+ * DebounceButton 的 props：复用 Button 的全部 props，并追加防抖参数。
+ */
+export const debounceButtonProps = {
+  ...buttonProps,
+  /** 防抖等待时间（ms） */
+  wait: { type: Number, default: 300 },
+  /**
+   * 是否前缘触发：首次点击立即触发，并在 wait 毫秒内锁定后续点击。
+   * 默认 false（后缘防抖：停止点击 wait 毫秒后才触发一次）。
+   */
+  leading: { type: Boolean, default: false },
+};

package/drawer/index.ts

@@ -0,0 +1,3 @@
+export { default as Drawer } from "./src/Drawer.vue";
+export { default } from "./src/Drawer.vue";
+export type * from "./src/types";

package/drawer/src/Drawer.vue

@@ -0,0 +1,120 @@
+<script setup lang="ts">
+import { ElDrawer } from "element-plus";
+import SunaButton from "../../button/src/Button.vue";
+import SunaDebounceButton from "../../debounce-button/src/DebounceButton.vue";
+import { drawerProps } from "./props";
+
+defineOptions({ name: "SunaDrawer" });
+
+// props 定义抽取到 ./props（运行时声明 + PropType，原因见该文件）
+defineProps(drawerProps);
+
+const emit = defineEmits<{
+  "update:modelValue": [value: boolean];
+  open: [];
+  opened: [];
+  close: [];
+  closed: [];
+  /** 点击「提交」按钮时触发 */
+  submit: [];
+  /** 点击「重置」按钮时触发 */
+  reset: [];
+  /** 点击「取消」按钮时触发 */
+  cancel: [];
+}>();
+
+// 显式声明的 props 之外，其余属性（before-close / append-to / z-index /
+// modal-class / class 等）与未声明的事件通过 attrs 自动透传给 ElDrawer。
+</script>
+
+<template>
+  <!--
+    基于 Element Plus 的 ElDrawer 封装：
+    - 声明的 props 显式绑定并设置了默认值；
+    - v-model 由 modelValue + update:modelValue 转发；
+    - open / opened / close / closed 四个生命周期事件透传；
+    - 透传 #header、#footer 与默认插槽（#header 携带 close 等作用域参数）。
+  -->
+  <ElDrawer
+    :model-value="modelValue"
+    :title="title"
+    :direction="direction"
+    :size="size"
+    :with-header="withHeader"
+    :show-close="showClose"
+    :modal="modal"
+    :close-on-click-modal="closeOnClickModal"
+    :close-on-press-escape="closeOnPressEscape"
+    :destroy-on-close="destroyOnClose"
+    :lock-scroll="lockScroll"
+    @update:model-value="emit('update:modelValue', $event)"
+    @open="emit('open')"
+    @opened="emit('opened')"
+    @close="emit('close')"
+    @closed="emit('closed')"
+  >
+    <template v-if="$slots.header" #header="headerProps">
+      <slot name="header" v-bind="headerProps" />
+    </template>
+    <template v-if="withFooter" #footer>
+      <!-- 提供 #footer 插槽时完全交由调用方自定义，不做任何布局约束 -->
+      <slot v-if="$slots.footer" name="footer" />
+      <!-- 否则渲染默认底部按钮「重置 / 取消 / 提交」，对齐方式由 footerAlign 控制 -->
+      <div v-else class="suna-drawer__footer" :class="`is-${footerAlign}`">
+        <SunaButton
+          v-if="showReset"
+          :type="resetButtonType"
+          @click="emit('reset')"
+        >
+          {{ resetText }}
+        </SunaButton>
+        <SunaButton
+          v-if="showCancel"
+          :type="cancelButtonType"
+          @click="emit('cancel')"
+        >
+          {{ cancelText }}
+        </SunaButton>
+        <!-- 提交按钮使用防抖按钮，避免重复提交；默认前缘触发（首次立即提交并锁定 wait 毫秒） -->
+        <SunaDebounceButton
+          v-if="showSubmit"
+          :type="submitButtonType"
+          :loading="submitLoading"
+          :wait="submitWait"
+          :leading="submitLeading"
+          @click="emit('submit')"
+        >
+          {{ submitText }}
+        </SunaDebounceButton>
+      </div>
+    </template>
+    <slot />
+  </ElDrawer>
+</template>
+
+<style scoped>
+/*
+  默认底部按钮容器。
+  el-drawer__footer 默认为 text-align:right（非 flex），这里用 flex + justify-content
+  精确控制左 / 居中 / 右对齐；width:100% 保证占满 footer 可用宽度。
+  该 div 由本组件渲染（携带 scoped 标记），即便被 ElDrawer teleport 到 body 仍可命中。
+*/
+.suna-drawer__footer {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  width: 100%;
+}
+
+.suna-drawer__footer.is-left {
+  justify-content: flex-start;
+}
+
+.suna-drawer__footer.is-center {
+  justify-content: center;
+}
+
+.suna-drawer__footer.is-right {
+  justify-content: flex-end;
+}
+</style>

package/drawer/src/props.ts

@@ -0,0 +1,76 @@
+import type { PropType } from "vue";
+import type { ButtonType } from "../../button/src/types";
+import type {
+  DrawerDirection,
+  DrawerSize,
+  DrawerFooterAlign,
+} from "./types";
+
+/**
+ * Drawer 的 props：抽屉显隐 / 方向 / 尺寸 + 默认底部操作栏（运行时声明，见同类文件说明）。
+ */
+export const drawerProps = {
+  /** 是否显示抽屉（支持 v-model） */
+  modelValue: { type: Boolean, default: false },
+  /** 抽屉标题，也可通过 #header 插槽自定义 */
+  title: { type: String, default: "" },
+  /** 抽屉滑出方向 */
+  direction: { type: String as PropType<DrawerDirection>, default: "rtl" },
+  /** 抽屉尺寸：数字为 px，字符串可为百分比 */
+  size: { type: [String, Number] as PropType<DrawerSize>, default: "30%" },
+  /** 是否显示头部 */
+  withHeader: { type: Boolean, default: true },
+  /** 是否显示关闭按钮 */
+  showClose: { type: Boolean, default: true },
+  /** 是否显示遮罩层 */
+  modal: { type: Boolean, default: true },
+  /** 点击遮罩层是否关闭抽屉 */
+  closeOnClickModal: { type: Boolean, default: true },
+  /** 按 ESC 是否关闭抽屉 */
+  closeOnPressEscape: { type: Boolean, default: true },
+  /** 关闭时是否销毁抽屉内的元素 */
+  destroyOnClose: { type: Boolean, default: false },
+  /** 是否在抽屉打开时锁定 body 滚动 */
+  lockScroll: { type: Boolean, default: true },
+
+  // ---- 默认底部操作栏 ----
+  // 未提供 #footer 插槽时，底部默认渲染「重置 / 取消 / 提交」按钮；
+  // 提供 #footer 插槽则完全交由调用方自定义（见 Drawer.vue 模板）。
+  /** 是否显示底部区域 */
+  withFooter: { type: Boolean, default: true },
+  /** 默认底部按钮的对齐方式 */
+  footerAlign: {
+    type: String as PropType<DrawerFooterAlign>,
+    default: "right",
+  },
+
+  // 重置按钮
+  /** 是否显示重置按钮 */
+  showReset: { type: Boolean, default: true },
+  /** 重置按钮文字 */
+  resetText: { type: String, default: "重置" },
+  /** 重置按钮类型 */
+  resetButtonType: { type: String as PropType<ButtonType>, default: "default" },
+
+  // 取消按钮
+  /** 是否显示取消按钮 */
+  showCancel: { type: Boolean, default: true },
+  /** 取消按钮文字 */
+  cancelText: { type: String, default: "取消" },
+  /** 取消按钮类型 */
+  cancelButtonType: { type: String as PropType<ButtonType>, default: "default" },
+
+  // 提交按钮（使用防抖按钮，避免重复提交）
+  /** 是否显示提交按钮 */
+  showSubmit: { type: Boolean, default: true },
+  /** 提交按钮文字 */
+  submitText: { type: String, default: "提交" },
+  /** 提交按钮类型 */
+  submitButtonType: { type: String as PropType<ButtonType>, default: "primary" },
+  /** 提交按钮是否加载中（异步提交时置 true，按钮自动禁用） */
+  submitLoading: { type: Boolean, default: false },
+  /** 提交按钮防抖等待时间（ms） */
+  submitWait: { type: Number, default: 300 },
+  /** 提交按钮是否前缘防抖：首次点击立即触发并锁定 wait 毫秒，避免重复提交 */
+  submitLeading: { type: Boolean, default: true },
+};

package/drawer/src/types.ts

@@ -0,0 +1,8 @@
+/** 抽屉滑出方向：rtl 右侧、ltr 左侧、ttb 顶部、btt 底部 */
+export type DrawerDirection = "rtl" | "ltr" | "ttb" | "btt";
+
+/** 抽屉尺寸：数字按 px 计算，字符串可用百分比（如 "30%"） */
+export type DrawerSize = string | number;
+
+/** 默认底部按钮的对齐方式 */
+export type DrawerFooterAlign = "left" | "center" | "right";

package/drawer-form/index.ts

@@ -0,0 +1,2 @@
+export { default as DrawerForm } from "./src/DrawerForm.vue";
+export { default } from "./src/DrawerForm.vue";