@scorpioz/suna-components

Suna Components

Vue 3 component library based on Element Plus.

Basic

• Button — action buttons with type/size/loading/icon support
• DebounceButton — click with debounce (trailing or leading)
• ConfirmButton — confirmation popover before executing actions

Container

• Drawer — slide-in panel with configurable direction/size/footer
• DrawerForm — Drawer + Form composition for create/edit flows
• Dialog — modal dialog on ElDialog with width/drag/fullscreen and a built-in reset/cancel/submit footer
• DialogForm — Dialog + Form composition for create/edit flows

Form

• Form — config-driven form (define fields via formItems array), with validation, layout grid, detail mode (read-only), and built-in action bar
• SearchForm — config-driven search form with inline query/reset toolbar and expand/collapse; emits search to drive data tables

Data display

• Table — config-driven table on el-table: built-in tag/switch/link/progress cells, formatters, multi-level headers, index/selection columns
• TableV2 — virtual-scroll table on el-table-v2 for large datasets, with formatters, slots, sorting, index/selection columns
• ProTable — remote-data table on Table: self-managed pagination + request (getTableData), auto-refetch on search params/sort, built-in toolbar (refresh + column setting)
• EmptyState — illustrated empty placeholder (image + description + extra slot); used as Table's default #empty
• EChart — ECharts wrapper with on-demand registration, auto-resize, loading, and full instance methods

Layout

• Grid — responsive CSS-Grid layout (xs/sm/md/lg/xl breakpoints) with span/offset/gap and collapse (search-form style)
• GridItem — grid cell with responsive span/offset, used inside Grid

Install

npm install @scorpioz/suna-components
# or
pnpm add @scorpioz/suna-components

Peer dependencies: vue ^3.5.0, element-plus ^2.14.0 (and echarts ^5.5.0 when using EChart).

Usage

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>, <SunaTable>, <SunaEChart>, <SunaGrid>, etc.

Custom prefix:

app.use(createComponents({ prefix: "S" }));
// <SButton>, <SForm>, <SDrawer>, <STable>, <SEChart>, <SGrid>, …

Global Config（全局配置）

所有组件都支持「全局修改默认 props」——无需在每个组件实例上逐个传参，只需在 createComponents({ config }) 中一次性配置，即可对所有实例生效。

优先级（高 → 低）：组件实例上显式传入的 prop > 全局 config 覆盖 > 组件内置默认。

典型场景：去掉所有 SearchForm 的 label 冒号、统一 Form 的 label 宽度、统一 Table 的分页布局等。

用法

在你自己的项目里新建一个配置文件（例如 src/suna.config.ts）：

// src/suna.config.ts
import type { SunaConfig } from "@scorpioz/suna-components";

export const sunaConfig: SunaConfig = {
  components: {
    // 去掉所有 SearchForm 的 label 冒号
    SearchForm: { labelSuffix: "" },
    // 统一 Form 的标签宽度与对齐
    Form: { labelWidth: "120px", labelPosition: "left" },
  },
};

在入口处传入：

import { createComponents } from "@scorpioz/suna-components";
import { sunaConfig } from "./suna.config";

app.use(createComponents({ config: sunaConfig }));

之后所有 <SunaSearchForm> 的 label 都会不带冒号，且单个实例仍可用 :label-suffix="':'" overriding 回默认值。

配置能力说明

• components 的键为组件 baseName（即 index.ts 中 componentList 的 baseName）。
• 已支持全局覆盖的组件（均在 shared/config.ts 的 SunaComponentConfigs 中登记）： Button、DebounceButton、ConfirmButton、Drawer、Dialog、DrawerForm、 DialogForm、SearchForm、Form、Table、TableV2、ProTable、 EmptyState、EChart、Grid、GridItem。
• 每个组件可覆盖的 props 即其 props 定义中的字段（必填项如 formItems/columns/data/option、 回调类如 onConfirm/getTableData、以及容器透传对象 drawerConfig/dialogConfig/formConfig 等不参与全局覆盖）；具体默认值见各组件 useResolvedProps(builtInDefaults) 调用处。

Import Style

Element Plus styles are imported once when you install the components:

import "element-plus/dist/index.css"; // already included via createComponents()

Docs

stay tuned