@scorpioz/suna-components 0.0.2

package/form/src/form-items/FText.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import { useFormField } from "../useFormField";
+
+const props = defineProps({
+  modelValue: { default: undefined },
+  item: { type: Object, default: () => ({}) },
+  form: { type: Object, default: () => ({}) },
+});
+const emit = defineEmits(["update:modelValue", "change"]);
+
+const { formatTextVal } = useFormField(props, emit);
+</script>
+
+<template>
+  <div class="suna-form__text">{{ formatTextVal }}</div>
+</template>

package/form/src/form-items/FTextarea.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import { ElInput } from "element-plus";
+import { useFormField } from "../useFormField";
+
+const props = defineProps({
+  modelValue: { default: undefined },
+  item: { type: Object, default: () => ({}) },
+  form: { type: Object, default: () => ({}) },
+});
+const emit = defineEmits(["update:modelValue", "change"]);
+
+const { valueTmp, showText, formatTextVal, handleChange, blur, focus } =
+  useFormField(props, emit);
+</script>
+
+<template>
+  <ElInput
+    v-if="!showText"
+    type="textarea"
+    :model-value="valueTmp"
+    v-bind="item.attrs"
+    @update:model-value="handleChange"
+    @blur="blur"
+    @focus="focus"
+  />
+  <span v-else class="suna-form__text">{{ formatTextVal }}</span>
+</template>

package/form/src/path.ts

@@ -0,0 +1,39 @@
+/**
+ * 按点号路径读取 / 写入对象嵌套字段。
+ * 仅覆盖配置驱动表单所需的最小能力，避免引入 lodash 依赖。
+ *
+ * @example
+ * getPath({ a: { b: 1 } }, "a.b") // => 1
+ * setPath(obj, "a.b", 2)          // obj.a.b === 2
+ */
+
+/** 读取 obj 上 path 对应的值；路径不存在返回 undefined。 */
+export function getPath(obj: Record<string, any> | undefined, path: string): any {
+  if (!obj || !path) return undefined;
+  return path.split(".").reduce((acc, key) => {
+    return acc == null ? acc : acc[key];
+  }, obj as any);
+}
+
+/**
+ * 在 obj 上按 path 写入 value，途中不存在的键会自动创建为对象。
+ * 就地修改并返回 obj。
+ */
+export function setPath(
+  obj: Record<string, any>,
+  path: string,
+  value: any
+): Record<string, any> {
+  if (!path) return obj;
+  const keys = path.split(".");
+  let cur = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (cur[key] == null || typeof cur[key] !== "object") {
+      cur[key] = {};
+    }
+    cur = cur[key];
+  }
+  cur[keys[keys.length - 1]] = value;
+  return obj;
+}

package/form/src/props.ts

@@ -0,0 +1,73 @@
+import type { PropType } from "vue";
+import type { ButtonType } from "../../button/src/types";
+import type { FormItem, FormFieldType } from "./types";
+
+/**
+ * SunaForm 的运行时 props 声明。
+ * 注：modelValue（表单数据对象）通过 defineModel 声明，不在此处。
+ */
+export const formProps = {
+  /** 字段配置数组 */
+  formItems: {
+    type: Array as PropType<FormItem[]>,
+    required: true as const,
+  },
+
+  // ---- el-form 显式暴露属性 ----
+  /** 标签宽度 */
+  labelWidth: { type: [String, Number], default: "100px" },
+  /** 标签对齐方式 */
+  labelPosition: {
+    type: String as PropType<"left" | "right" | "top">,
+    default: "right",
+  },
+  /** 表单控件尺寸 */
+  size: {
+    type: String as PropType<"large" | "default" | "small">,
+    default: "default",
+  },
+  /** 栅格间隔（px） */
+  gutter: { type: Number, default: 12 },
+  /** 未指定 span 时的默认栅格占比（默认 12 = 两列） */
+  defaultSpan: { type: Number, default: 12 },
+
+  // ---- 渲染模式 ----
+  /** 渲染模式：normal 可编辑 / text 只读详情 */
+  showType: {
+    type: String as PropType<"normal" | "text">,
+    default: "normal",
+  },
+
+  // ---- 内置底部操作栏（语义同 Drawer footer，保持一致） ----
+  /** 是否显示操作栏 */
+  withActions: { type: Boolean, default: true },
+  /** 按钮对齐方式 */
+  actionAlign: {
+    type: String as PropType<"left" | "center" | "right">,
+    default: "right",
+  },
+  /** 是否显示提交按钮 */
+  showSubmit: { type: Boolean, default: true },
+  /** 是否显示重置按钮 */
+  showReset: { type: Boolean, default: true },
+  /** 是否显示取消按钮 */
+  showCancel: { type: Boolean, default: true },
+  /** 提交按钮文字 */
+  submitText: { type: String, default: "提交" },
+  /** 重置按钮文字 */
+  resetText: { type: String, default: "重置" },
+  /** 取消按钮文字 */
+  cancelText: { type: String, default: "取消" },
+  /** 提交按钮类型 */
+  submitButtonType: { type: String as PropType<ButtonType>, default: "primary" },
+  /** 重置按钮类型 */
+  resetButtonType: { type: String as PropType<ButtonType>, default: "default" },
+  /** 取消按钮类型 */
+  cancelButtonType: { type: String as PropType<ButtonType>, default: "default" },
+  /** 提交按钮加载中 */
+  submitLoading: { type: Boolean, default: false },
+  /** 提交按钮防抖等待时间（ms） */
+  submitWait: { type: Number, default: 300 },
+  /** 提交按钮是否前缘防抖 */
+  submitLeading: { type: Boolean, default: true },
+};

package/form/src/types.ts

@@ -0,0 +1,168 @@
+import type {
+  InputProps,
+  InputNumberProps,
+  SelectProps,
+  SwitchProps,
+  RadioGroupProps,
+  CheckboxGroupProps,
+  DatePickerProps,
+  CascaderProps,
+  RateProps,
+  FormItemRule,
+} from "element-plus";
+
+/**
+ * 配置驱动的 Form 字段类型定义。
+ *
+ * 设计：以 `type` 作为判别字段的「可辨识联合」(discriminated union)，
+ * 每个变体的 `attrs` 精确指向对应 Element Plus 控件的 props，从而在书写配置时
+ * 获得 `attrs` 的自动补全与类型校验。
+ */
+
+/** 选项字段名自定义（用于 select / radio / checkbox / cascader 的 options） */
+export interface OptionFieldProps {
+  /** 选项的 label 取值字段，默认 "label" */
+  label?: string;
+  /** 选项的 value 取值字段，默认 "value" */
+  value?: string;
+  /** 选项是否禁用取值字段，默认 "disabled" */
+  disabled?: string;
+  /** 级联子节点取值字段（cascader），默认 "children" */
+  children?: string;
+}
+
+/** 详情模式（showType: "text"）下的文本格式化：函数 或 value→文本 的映射 */
+export type FormatterText =
+  | ((value: any, form: Record<string, any>) => any)
+  | Record<string | number, any>;
+
+/** 所有字段配置的公共基础 */
+export interface BaseFormItem {
+  /** 字段在表单数据中的 key；支持点号嵌套路径，如 "user.name" */
+  prop?: string;
+  /** 标签文字 */
+  label?: string;
+  /** 栅格占比（1-24）；不传则使用表单的 defaultSpan */
+  span?: number;
+  /** 栅格左侧偏移 */
+  offset?: number;
+  /** 是否显示该项，默认 true */
+  showItem?: boolean;
+  /** 用具名插槽整体替换该项的渲染（不渲染内置控件） */
+  slot?: string;
+  /** 是否必填：为 true 时自动追加必填校验规则与「*」标记 */
+  required?: boolean;
+  /** 显式校验规则，与自动必填规则合并后传给 el-form-item */
+  rules?: FormItemRule[];
+  /** 标签后的提示信息（tooltip） */
+  tooltip?: string;
+  /** 该项 label 宽度，覆盖表单级 labelWidth */
+  labelWidth?: string | number;
+  /** 详情模式下的文本格式化 */
+  formatterText?: FormatterText;
+  /** 值变化回调 */
+  onChange?: (value: any, form: Record<string, any>) => void;
+}
+
+export interface InputFormItem extends BaseFormItem {
+  type: "input";
+  /** 透传给 ElInput 的属性（modelValue 由表单接管，请勿在此设置） */
+  attrs?: Partial<InputProps>;
+}
+
+export interface TextareaFormItem extends BaseFormItem {
+  type: "textarea";
+  /** 透传给 ElInput（type=textarea）；rows / autosize 等写在这里 */
+  attrs?: Partial<InputProps>;
+}
+
+export interface SelectFormItem extends BaseFormItem {
+  type: "select";
+  /** 选项数组 */
+  options: Record<string, any>[];
+  /** 选项字段名自定义 */
+  optionProps?: OptionFieldProps;
+  /** 透传给 ElSelect 的属性 */
+  attrs?: Partial<SelectProps>;
+}
+
+export interface RadioGroupFormItem extends BaseFormItem {
+  type: "radio-group";
+  options: Record<string, any>[];
+  optionProps?: OptionFieldProps;
+  /** 透传给 ElRadioGroup 的属性 */
+  attrs?: Partial<RadioGroupProps>;
+}
+
+export interface CheckboxGroupFormItem extends BaseFormItem {
+  type: "checkbox-group";
+  options: Record<string, any>[];
+  optionProps?: OptionFieldProps;
+  /** 透传给 ElCheckboxGroup 的属性 */
+  attrs?: Partial<CheckboxGroupProps>;
+}
+
+export interface SwitchFormItem extends BaseFormItem {
+  type: "switch";
+  /** 透传给 ElSwitch 的属性 */
+  attrs?: Partial<SwitchProps>;
+}
+
+export interface InputNumberFormItem extends BaseFormItem {
+  type: "input-number";
+  /** 透传给 ElInputNumber 的属性 */
+  attrs?: Partial<InputNumberProps>;
+}
+
+export interface DatePickerFormItem extends BaseFormItem {
+  type: "date-picker";
+  /** 透传给 ElDatePicker 的属性 */
+  attrs?: Partial<DatePickerProps>;
+}
+
+export interface CascaderFormItem extends BaseFormItem {
+  type: "cascader";
+  options: Record<string, any>[];
+  optionProps?: OptionFieldProps;
+  /** 透传给 ElCascader 的属性 */
+  attrs?: Partial<CascaderProps>;
+}
+
+export interface RateFormItem extends BaseFormItem {
+  type: "rate";
+  /** 透传给 ElRate 的属性 */
+  attrs?: Partial<RateProps>;
+}
+
+/** 纯文本展示项（始终只读，常用于在可编辑表单中嵌入不可编辑信息） */
+export interface TextFormItem extends BaseFormItem {
+  type: "text";
+}
+
+/** 内置支持的字段类型联合 */
+export type FormItemType =
+  | InputFormItem
+  | TextareaFormItem
+  | SelectFormItem
+  | RadioGroupFormItem
+  | CheckboxGroupFormItem
+  | SwitchFormItem
+  | InputNumberFormItem
+  | DatePickerFormItem
+  | CascaderFormItem
+  | RateFormItem
+  | TextFormItem;
+
+/** 纯插槽项：不渲染任何控件，仅占用栅格并交给具名插槽 */
+export interface SlotItem {
+  slot: string;
+  span?: number;
+  offset?: number;
+  showItem?: boolean;
+}
+
+/** 一个表单项 = 内置字段类型 或 纯插槽项 */
+export type FormItem = FormItemType | SlotItem;
+
+/** 字段 type 取值（用于校验/映射） */
+export type FormFieldType = FormItemType["type"];

package/form/src/useFormField.ts

@@ -0,0 +1,137 @@
+import { ref, watchEffect, computed, inject } from "vue";
+import type { ComputedRef } from "vue";
+
+const SHOW_TYPE_KEY = "suna:showType";
+
+/**
+ * 字段组件级 composable：管理 v-model 代理、详情文本、选项文本回显。
+ *
+ * 在每个 F*.vue 的 setup 中调用：
+ * ```ts
+ * const field = useFormField(props, emit)
+ * ```
+ */
+export function useFormField(
+  props: {
+    modelValue?: any;
+    item: Record<string, any>;
+    form: Record<string, any>;
+  },
+  emit: {
+    (e: "update:modelValue", val: any): void;
+    (e: "change", val: any): void;
+  }
+) {
+  // ---- 值代理 ----
+  const valueTmp = ref(props.modelValue);
+  watchEffect(() => {
+    valueTmp.value = props.modelValue;
+  });
+
+  // ---- 详情/只读模式（表单级控制） ----
+  const showType = inject<ComputedRef<"normal" | "text"> | null>(SHOW_TYPE_KEY, null);
+  const showText = computed(() => showType?.value === "text");
+
+  // ---- 详情文本格式化 ----
+  const formatTextVal = computed(() => {
+    // 情况检查：如果 item 上没有 formatterText，直接返回原始值
+    const item = props.item as any;
+    const value = props.modelValue;
+    if (!item?.formatterText) {
+      // 级联需要树形遍历回显，formatterText 也走下面统一出口
+      if (item?.type === "cascader") {
+        return getCascaderLabel(item.options || [], value);
+      }
+      // select/radio/checkbox 需要扁平选项回显
+      if (["select", "radio-group", "checkbox-group"].includes(item?.type)) {
+        return _resolveOptionLabel(value);
+      }
+      return value ?? "";
+    }
+    // 函数格式化
+    if (typeof item.formatterText === "function") {
+      return item.formatterText(value, props.form);
+    }
+    // 映射格式化
+    return item.formatterText[value] ?? value ?? "";
+  });
+
+  // ---- 选项文本回显 ----
+  function _resolveOptionLabel(value: any): string | any[] {
+    const item = props.item as any;
+    const options: Record<string, any>[] = item.options || [];
+    const optProps = Object.assign(
+      { label: "label", value: "value" },
+      item.optionProps || {}
+    );
+    if (Array.isArray(value)) {
+      return value
+        .map((v) => {
+          const opt = options.find((o) => o[optProps.value] === v);
+          return opt ? opt[optProps.label] : v;
+        })
+        .filter(Boolean)
+        .join(", ");
+    }
+    const opt = options.find((o) => o[optProps.value] === value);
+    return opt ? opt[optProps.label] : value;
+  }
+
+  // ---- 级联选中项完整文本 ----
+  function getCascaderLabel(list: Record<string, any>[], val: any): string {
+    if (!list || !val) return val;
+    const optProps = Object.assign(
+      { label: "label", value: "value", children: "children" },
+      (props.item as any)?.optionProps || {}
+    );
+    const parts: string[] = [];
+    const path = Array.isArray(val) ? val : [val];
+    let nodes = list;
+    for (const v of path) {
+      const node = nodes.find((n) => n[optProps.value] === v);
+      if (!node) break;
+      parts.push(node[optProps.label] as string);
+      nodes = node[optProps.children] || [];
+    }
+    return parts.join(" / ");
+  }
+
+  // ---- 事件转发 ----
+  const handleChange = (val: any) => {
+    emit("update:modelValue", val);
+    emit("change", val);
+    (props.item as any)?.onChange?.(val, props.form);
+  };
+
+  const handleInput = (val: string) => {
+    emit("update:modelValue", val);
+    (props.item as any)?.onInput?.(val);
+  };
+
+  const clear = () => {
+    emit("update:modelValue", null);
+    (props.item as any)?.clear?.();
+  };
+
+  const blur = (evt: any) => {
+    (props.item as any)?.blur?.(evt);
+  };
+  const focus = (evt: any) => {
+    (props.item as any)?.focus?.(evt);
+  };
+
+  return {
+    valueTmp,
+    showText,
+    formatTextVal,
+    resolveOptionLabel: _resolveOptionLabel,
+    getCascaderLabel,
+    handleChange,
+    handleInput,
+    clear,
+    blur,
+    focus,
+  };
+}
+
+export type UseFormFieldReturn = ReturnType<typeof useFormField>;

package/form/src/useFormItems.ts

@@ -0,0 +1,85 @@
+import type { Component } from "vue";
+import type { FormItemRule } from "element-plus";
+import FInput from "./form-items/FInput.vue";
+import FTextarea from "./form-items/FTextarea.vue";
+import FSelect from "./form-items/FSelect.vue";
+import FRadioGroup from "./form-items/FRadioGroup.vue";
+import FCheckboxGroup from "./form-items/FCheckboxGroup.vue";
+import FSwitch from "./form-items/FSwitch.vue";
+import FInputNumber from "./form-items/FInputNumber.vue";
+import FDatePicker from "./form-items/FDatePicker.vue";
+import FCascader from "./form-items/FCascader.vue";
+import FRate from "./form-items/FRate.vue";
+import FText from "./form-items/FText.vue";
+import type { FormItem, FormFieldType } from "./types";
+
+/**
+ * 表单级 composable：将字段配置映射为组件、生成校验规则、计算栅格跨度。
+ */
+export function useFormItems(defaultSpan: number) {
+  /** type → component 映射 */
+  const componentMap: Record<string, Component> = {
+    input: FInput,
+    textarea: FTextarea,
+    select: FSelect,
+    "radio-group": FRadioGroup,
+    "checkbox-group": FCheckboxGroup,
+    switch: FSwitch,
+    "input-number": FInputNumber,
+    "date-picker": FDatePicker,
+    cascader: FCascader,
+    rate: FRate,
+    text: FText,
+  };
+
+  /** 根据 type 获取对应的字段组件 */
+  function getType(type: string | undefined): Component | undefined {
+    if (!type) return undefined;
+    return componentMap[type];
+  }
+
+  /**
+   * 为表单项生成校验规则：
+   * - `required: true` 自动生成必填规则
+   * - 与 `item.rules` 数组合并
+   * - 输入型（input/textarea）默认 trigger = "blur"，选择型默认 trigger = "change"
+   */
+  function getRules(item: FormItem): FormItemRule[] {
+    const itemAny = item as any;
+    // 非字段配置项（纯插槽）直接返回空规则
+    if (itemAny.type == null) return [];
+
+    const isInput = ["input", "textarea"].includes(itemAny.type);
+    const trigger = (itemAny.trigger as string) || (isInput ? "blur" : "change");
+    const rules: FormItemRule[] = [];
+
+    // 自动必填规则
+    if (itemAny.required) {
+      const triggerMessage = isInput ? "请输入" : "请选择";
+      rules.push({
+        required: true,
+        message: `${triggerMessage}${itemAny.label ?? ""}`,
+        trigger: trigger as "blur" | "change",
+      });
+    }
+
+    // 用户自定义规则（合并）
+    if (itemAny.rules) {
+      if (Array.isArray(itemAny.rules)) {
+        rules.push(...itemAny.rules);
+      } else {
+        rules.push(itemAny.rules);
+      }
+    }
+
+    return rules;
+  }
+
+  /** 计算该字段占据的栅格列数 */
+  function getSpan(item: FormItem): number {
+    const itemAny = item as any;
+    return itemAny.span ?? defaultSpan;
+  }
+
+  return { getType, getRules, getSpan };
+}

package/index.ts

@@ -0,0 +1,82 @@
+import type { App, Component } from "vue";
+// 全局引入 Element Plus 完整样式（只需一次，各组件内不再单独 import xxx.css）。
+// 使用纯 CSS 的 dist/index.css，而非 element-plus/es/.../style/css 入口——
+// 后者在 VitePress SSR 构建时会被 Node 原生 ESM 加载器当作 JS 解析而报错。
+import "element-plus/dist/index.css";
+import { Button } from "./button";
+import { DebounceButton } from "./debounce-button";
+import { ConfirmButton } from "./confirm-button";
+import { Drawer } from "./drawer";
+import { Form } from "./form";
+import { DrawerForm } from "./drawer-form";
+
+/** 组件清单：新增组件时在此登记，baseName 为去掉前缀后的 PascalCase 名称 */
+interface ComponentItem {
+  baseName: string;
+  component: Component;
+}
+
+const componentList: ComponentItem[] = [
+  { baseName: "Button", component: Button },
+  { baseName: "DebounceButton", component: DebounceButton },
+  { baseName: "ConfirmButton", component: ConfirmButton },
+  { baseName: "Form", component: Form },
+  { baseName: "DrawerForm", component: DrawerForm },
+];
+
+/** 将任意前缀转为 PascalCase：suna -> Suna、my-ui -> MyUi、s -> S */
+function toPascalCase(str: string): string {
+  return str
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join("");
+}
+
+export interface CreateComponentsOptions {
+  /** 组件注册前缀，默认 "suna" */
+  prefix?: string;
+}
+
+export interface ComponentsPlugin {
+  prefix: string;
+  install: (app: App) => void;
+}
+
+/**
+ * 创建可配置前缀的组件库插件。
+ *
+ * @example
+ * // 默认前缀 suna —— 注册为 <SunaButton />
+ * app.use(createComponents())
+ *
+ * // 自定义前缀 —— 注册为 <SButton />、<MyButton /> 等
+ * app.use(createComponents({ prefix: "S" }))
+ * app.use(createComponents({ prefix: "my" }))
+ */
+export function createComponents(
+  options: CreateComponentsOptions = {}
+): ComponentsPlugin {
+  const prefix = options.prefix ?? "suna";
+  return {
+    prefix,
+    install(app: App) {
+      const namespace = toPascalCase(prefix);
+      componentList.forEach(({ baseName, component }) => {
+        app.component(namespace + baseName, component);
+      });
+    },
+  };
+}
+
+export { Button, DebounceButton, ConfirmButton, Drawer, Form, DrawerForm };
+export type {
+  ButtonType,
+  ButtonSize,
+  NativeButtonType,
+  ElButtonType,
+} from "./button";
+export type { DrawerDirection, DrawerSize, DrawerFooterAlign } from "./drawer";
+
+/** 默认插件：等价于 createComponents({ prefix: "suna" })，注册为 <SunaButton /> */
+export default createComponents();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@scorpioz/suna-components",
+  "version": "0.0.2",
+  "description": "Vue 3 component library based on Element Plus – config-driven Form, configurable Drawer, debounce/confirm buttons, and more.",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "button/",
+    "debounce-button/",
+    "confirm-button/",
+    "drawer/",
+    "drawer-form/",
+    "form/",
+    "package.json",
+    "README.md"
+  ],
+  "main": "./index.ts",
+  "module": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "sideEffects": [
+    "./index.ts"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "vue",
+    "vue3",
+    "element-plus",
+    "component",
+    "form",
+    "drawer"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scorpioz/web-component.git"
+  },
+  "bugs": {
+    "url": "https://github.com/scorpioz/web-component/issues"
+  },
+  "homepage": "https://github.com/scorpioz/web-component#readme",
+  "peerDependencies": {
+    "element-plus": "^2.14.0",
+    "vue": "^3.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}