@owocow/saber-ui 0.0.2 → 0.0.3

package/README.md

@@ -1,6 +1,16 @@
 # @owocow/saber-ui
 
-Vue 3 component library — BadgeStatus and more, built on top of [@nuxt/ui](https://ui.nuxt.com).
+Saber application foundation for Vue 3 projects, built on top of [@nuxt/ui](https://ui.nuxt.com).
+
+## Documentation
+
+The VitePress documentation site lives in `docs/` and runs directly against the local `src/` code:
+
+```bash
+pnpm docs:dev
+pnpm docs:build
+pnpm docs:preview
+```
 
 ## Install
 
@@ -10,24 +20,39 @@ npm install @owocow/saber-ui @nuxt/ui
 
 > Requires: `vue` ^3, `@nuxt/ui` ^4
 
-## Usage
-
-### Setup (recommended)
+## Consumption contract
 
-```bash
-npm install @owocow/saber-ui @nuxt/ui
-```
+> **重要**:saber-ui 的组件在宿主编译时需要 nuxt/ui 的 `#imports` / `#build/*` 虚拟模块,
+> **任何使用 saber-ui 的宿主都必须运行 `@nuxt/ui/vite`**(Vite 项目下让 nuxt/ui 脱离 Nuxt 运行的标准插件)。
+> 不满足该条件时,组件内的 `<UBadge>` / `<UIcon>` 与主题配置将无法解析。
 
 ```ts
 // vite.config.ts
 import vue from '@vitejs/plugin-vue'
-import saberUI from '@owocow/saber-ui/vite'
+import ui from '@nuxt/ui/vite'
 
 export default defineConfig({
-  plugins: [vue(), saberUI()],
+  plugins: [
+    vue(),
+    ui({
+      theme: {
+        colors: ['primary', 'secondary', 'success', 'info', 'warning', 'error'],
+      },
+      // ... 主题配置会同样作用到 saber-ui 内部的 nuxt/ui 组件
+    }),
+  ],
 })
 ```
 
+> **关于 `@owocow/saber-ui/vite`**:它只是 `@nuxt/ui/vite` 的**转发导出**(re-export),
+> saber-ui **不自带** Vite 插件。直接使用 `@nuxt/ui/vite` 即可,不必引入这个入口。
+
+## Usage
+
+```bash
+npm install @owocow/saber-ui @nuxt/ui
+```
+
 ```ts
 // main.ts
 import { createApp } from 'vue'
@@ -51,7 +76,7 @@ app.mount('#app')
 
 ### On-demand import
 
-If you don't need the Vite plugin, import components directly:
+组件始终需要宿主提供 `@nuxt/ui/vite`,此处仅指按需引入组件而不是注册全部:
 
 ```vue
 <script setup>
@@ -66,7 +91,177 @@ import { BadgeStatus } from '@owocow/saber-ui'
 </template>
 ```
 
-> **Note**: Without `@owocow/saber-ui/vite`, you need to configure `@nuxt/ui/vite` manually in your `vite.config.ts` and import Nuxt UI CSS manually.
+## Forms
+
+`app.use(SaberUI)` 会全局注册 `SaberFilterBar`、`SaberFormModal`、`SaberModal` 和基础 Saber 字段，并为动态字段提供 app 级 registry。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { FilterField } from '@owocow/saber-ui/forms'
+
+const params = ref({ keyword: '', status: undefined })
+
+const fields: FilterField[] = [
+  {
+    key: 'keyword',
+    which: 'ui-input',
+    props: { placeholder: '搜索名称' },
+  },
+  {
+    key: 'status',
+    which: 'ui-select',
+    props: { items: [{ label: '启用', value: 'enabled' }] },
+    searchOn: 'update:model-value',
+  },
+]
+</script>
+
+<template>
+  <SaberFilterBar v-model="params" :fields="fields" @search="loadData" @reset="resetParams" />
+</template>
+```
+
+基础 registry 包含 `saber-input`、`saber-select` 等 Saber 字段，以及 `ui-input`、`ui-select`、`ui-textarea` 等 Nuxt UI 原生字段映射。
+
+文本输入默认在 `change` 时触发搜索；Select、Radio 等值变更后立即搜索的字段应设置 `searchOn: 'update:model-value'`。复杂业务字段可使用 `searchOn: 'manual'`。
+
+项目自定义字段在安装时提供：
+
+```ts
+import SaberUI from '@owocow/saber-ui'
+import SupplierPicker from './SupplierPicker.vue'
+
+app.use(SaberUI, {
+  forms: {
+    components: {
+      'supplier-picker': SupplierPicker,
+    },
+  },
+})
+```
+
+字典字段由宿主提供数据源，saber-ui 不依赖具体 store 或接口：
+
+```ts
+const dictStore = useDictStore()
+
+app.use(SaberUI, {
+  forms: {
+    dictDataSource: {
+      async loadOptions(dictType) {
+        await dictStore.loadDict(dictType)
+        return dictStore.getOptions(dictType)
+      },
+    },
+  },
+})
+```
+
+配置后可使用 `saber-dict-radio`、`saber-dict-select`、`saber-dict-checkbox`，或直接使用全局组件 `SaberDictRadio`、`SaberDictSelect`、`SaberDictCheckbox`。`SaberDictSelect` 基于 `SaberPopSelect`，适合在 Modal 中使用。
+
+行政区划选择和地址解析共用 app 级地区服务。使用内置高德数据源时只需配置 Web 服务 Key：
+
+```ts
+app.use(SaberUI, {
+  forms: {
+    district: {
+      amapKey: import.meta.env.VITE_APP_AMAP_KEY,
+    },
+  },
+})
+```
+
+配置后，动态表单可直接使用 `saber-district-select`，无需页面引入组件、加载数据或传递 `districts`：
+
+```ts
+const fields = [{
+  key: 'districtValue',
+  label: '所在地区',
+  which: 'saber-district-select',
+}]
+```
+
+地区数据仅在 `SaberDistrictSelect` 首次渲染或地址首次解析时加载；内置高德数据源默认使用 7 天 localStorage 缓存。也可以通过 `forms.district.dataSource` 替换成其他数据源。
+
+自定义数据源、`DistrictService` 和区划类型可从 `@owocow/saber-ui/district` 独立导入；该入口不加载 UI 组件。
+
+图片上传组件通过独立入口按需使用，上传、删除和响应字段由宿主适配：
+
+```ts
+import type { UploadImageDataSource } from '@owocow/saber-ui/forms'
+
+const uploadImageDataSource: UploadImageDataSource<{ ossId: string; url: string }> = {
+  upload: (file, { onProgress }) => uploadFile(file, onProgress),
+  remove: value => deleteFile(value.ossId),
+  getKey: value => value.ossId,
+  getUrl: value => value.url,
+}
+
+app.use(SaberUI, {
+  forms: { uploadImageDataSource },
+})
+```
+
+```vue
+<script setup lang="ts">
+import SaberUploadImage from '@owocow/saber-ui/forms/upload-image'
+</script>
+
+<template>
+  <SaberUploadImage v-model="avatar" />
+</template>
+```
+
+`SaberUploadImage` 不进入默认 registry；动态表单需要使用时可按页面注册 `saber-upload-image`。远程删除适配器会收到 `initial` 或 `uploaded` 来源，宿主可据此决定是否立即删除文件。
+
+## Utilities
+
+通用应用能力通过独立子路径提供，不会从 `@owocow/saber-ui` 根入口自动加载：
+
+```ts
+import { setupHttp, http } from '@owocow/saber-ui/utils/http'
+import { setupStorage, storage } from '@owocow/saber-ui/utils/storage'
+import { setupPermission, canAccess } from '@owocow/saber-ui/utils/permission'
+import { getToast, setToast } from '@owocow/saber-ui/utils/toast'
+```
+
+Vue 组件内推荐使用 composable；它会自动等待安装时配置的共享地区服务，并复用地址解析索引：
+
+```ts
+import { useAddressParse } from '@owocow/saber-ui/composables/use-address-parse'
+
+const { parseAddress } = useAddressParse()
+const results = await parseAddress('张三 浙江省杭州市西湖区文三路90号 13800138000', true)
+```
+
+底层地址解析器仍是纯函数，适用于 Node 脚本、单元测试或自定义数据：
+
+```ts
+import { createAddressParser } from '@owocow/saber-ui/utils/addressParse'
+const parser = createAddressParser(customDistricts)
+const results = parser.parse('张三 浙江省杭州市西湖区文三路90号 13800138000', true)
+```
+
+行政区划节点至少需要包含 `name`、`adcode` 和可选的 `districts`。传入数据应以省级节点作为数组第一层；底层解析器不会请求网络，也不会依赖 Vue。
+
+可用入口包括 `http`、`storage`、`rsa`、`crypto`、`permission`、`toast`、`format`、`filter`、`tree`、`klona`、`nanoid` 和 `addressParse`。
+
+公共后端协议和基础类型通过独立入口导入：
+
+```ts
+import type { ApiResponse, AuthUserInfo, Id, ListResponse, PageParams } from '@owocow/saber-ui/types'
+```
+
+该入口只包含基础、API 和认证协议类型，不包含具体 System 或业务 DTO。
+
+`http`、`storage`、`rsa`、`crypto` 与 `toast` 共享模块级初始化状态，迁移或初始化时应始终从 `@owocow/saber-ui/utils/*` 引用，不能与旧的 `@owocow/saber-utils/*` 混用。
+
+### 版本对齐
+
+`saber-ui` 通过 `@nuxt/ui` 的裸导入引用宿主的 nuxt/ui 副本,请保持 `@nuxt/ui`
+主版本(^4)一致;宿主如遇解析到多份副本,可在 Vite 配置中加
+`resolve: { dedupe: ['@nuxt/ui', '@nuxt/icon'] }` 强制解析到宿主副本。
 
 ## Components
 

package/dist/BadgeStatus.types.d.ts

@@ -6,5 +6,5 @@ export interface BadgeStatusProps {
     /** 背景色透明度（Tailwind opacity 数值），默认 20 */
     bgOpacity?: number;
     /** 文字颜色色阶权重（Tailwind 色阶），默认 500 */
-    textColorWeight?: number;
+    textColorWeight?: 500 | 600;
 }

package/dist/BadgeStatus.vue.d.ts

@@ -1,6 +1,6 @@
 import { BadgeStatusProps } from './BadgeStatus.types';
 declare const _default: import('vue').DefineComponent<BadgeStatusProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<BadgeStatusProps> & Readonly<{}>, {
     bgOpacity: number;
-    textColorWeight: number;
+    textColorWeight: 500 | 600;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 export default _default;

package/dist/SaberConfirmModal.vue_vue_type_script_setup_true_lang-Cqp9krYl.js

@@ -0,0 +1,86 @@
+import k from "@nuxt/ui/components/Modal.vue";
+import C from "@nuxt/ui/components/Button.vue";
+import h from "@nuxt/ui/runtime/vue/components/Icon.vue";
+import { defineComponent as B, useModel as M, computed as u, openBlock as f, createBlock as z, withCtx as i, createElementVNode as n, normalizeClass as p, createVNode as c, toDisplayString as r, createElementBlock as N, createCommentVNode as U, createTextVNode as _, mergeModels as v } from "vue";
+const V = { class: "relative z-10 flex flex-col items-center text-center gap-8" }, S = { class: "w-full sm:w-60" }, T = { class: "font-bold mb-3 text-xl" }, D = {
+  key: 0,
+  class: "mt-1 text-sm"
+}, E = { class: "flex w-full justify-center gap-3 sm:gap-4" }, A = /* @__PURE__ */ B({
+  name: "SaberConfirmModal",
+  __name: "SaberConfirmModal",
+  props: /* @__PURE__ */ v({
+    name: {},
+    icon: { default: "i-solar:info-circle-linear" },
+    title: { default: "确认操作" },
+    description: { default: "" },
+    confirmLoading: { type: Boolean, default: !1 },
+    type: { default: "delete" },
+    confirmText: {}
+  }, {
+    open: { type: Boolean, default: !1 },
+    openModifiers: {}
+  }),
+  emits: /* @__PURE__ */ v(["confirm", "cancel"], ["update:open"]),
+  setup(e, { emit: x }) {
+    const l = M(e, "open"), a = e, s = x, t = u(() => a.type === "delete"), b = u(() => a.icon || a.name || "i-solar:info-circle-linear");
+    function g() {
+      l.value = !1, s("cancel");
+    }
+    return (L, o) => {
+      const w = h, d = C, y = k;
+      return f(), z(y, {
+        open: l.value,
+        "onUpdate:open": o[1] || (o[1] = (m) => l.value = m),
+        close: !1,
+        ui: { overlay: "z-100", content: "rounded-xl shadow-sm w-full sm:w-110 max-w-[calc(100vw-2rem)] z-100", body: "p-6 sm:p-8" }
+      }, {
+        body: i(() => [
+          n("div", V, [
+            n("div", {
+              class: p(["rounded-md border p-2.5", t.value ? "border-red-300 bg-red-50 dark:bg-red-950/30" : "border-accented"])
+            }, [
+              c(w, {
+                name: b.value,
+                class: p(["size-8", t.value ? "text-red-500" : ""])
+              }, null, 8, ["name", "class"])
+            ], 2),
+            n("div", S, [
+              n("h4", T, r(e.title), 1),
+              e.description ? (f(), N("p", D, r(e.description), 1)) : U("", !0)
+            ]),
+            n("div", E, [
+              c(d, {
+                color: "neutral",
+                block: "",
+                ui: { base: "w-30 h-9" },
+                variant: "outline",
+                onClick: g
+              }, {
+                default: i(() => [...o[2] || (o[2] = [
+                  _("取消", -1)
+                ])]),
+                _: 1
+              }),
+              c(d, {
+                color: t.value ? "error" : "primary",
+                loading: e.confirmLoading,
+                block: "",
+                ui: { base: "w-30 h-9" },
+                onClick: o[0] || (o[0] = (m) => s("confirm"))
+              }, {
+                default: i(() => [
+                  _(r(e.confirmText ?? (t.value ? "确认删除" : "确定")), 1)
+                ]),
+                _: 1
+              }, 8, ["color", "loading"])
+            ])
+          ])
+        ]),
+        _: 1
+      }, 8, ["open"]);
+    };
+  }
+});
+export {
+  A as _
+};

package/dist/SaberConfirmProvider.vue_vue_type_script_setup_true_lang-DUJ6ftNJ.js

@@ -0,0 +1,30 @@
+import { defineComponent as m, watch as p, openBlock as f, createBlock as s, unref as o } from "vue";
+import { settleConfirm as r, useConfirmState as a } from "./composables/use-confirm.mjs";
+import { _ as l } from "./SaberConfirmModal.vue_vue_type_script_setup_true_lang-Cqp9krYl.js";
+const _ = /* @__PURE__ */ m({
+  name: "SaberConfirmProvider",
+  __name: "SaberConfirmProvider",
+  setup(c) {
+    const e = a();
+    return p(
+      () => e.open,
+      (i) => {
+        !i && e.resolve && r(!1);
+      }
+    ), (i, n) => (f(), s(l, {
+      open: o(e).open,
+      "onUpdate:open": n[0] || (n[0] = (t) => o(e).open = t),
+      title: o(e).title,
+      description: o(e).message,
+      icon: o(e).icon,
+      type: o(e).type,
+      "confirm-loading": o(e).loading,
+      "confirm-text": o(e).confirmText,
+      onConfirm: n[1] || (n[1] = (t) => o(r)(!0)),
+      onCancel: n[2] || (n[2] = (t) => o(r)(!1))
+    }, null, 8, ["open", "title", "description", "icon", "type", "confirm-loading", "confirm-text"]));
+  }
+});
+export {
+  _
+};

package/dist/SaberDictCheckbox.vue_vue_type_script_setup_true_lang-DUbzy_C6.js

@@ -0,0 +1,34 @@
+import b from "@nuxt/ui/components/CheckboxGroup.vue";
+import { defineComponent as _, useModel as h, toRef as n, openBlock as g, createBlock as k, mergeProps as x, unref as s, mergeModels as i } from "vue";
+import { u as V } from "./use-dict-options-DjtbYYIa.js";
+const B = /* @__PURE__ */ _({
+  name: "SaberDictCheckbox",
+  inheritAttrs: !1,
+  __name: "SaberDictCheckbox",
+  props: /* @__PURE__ */ i({
+    dictType: {},
+    dataSource: { default: void 0 },
+    disabled: { type: Boolean, default: !1 }
+  }, {
+    modelValue: { default: () => [] },
+    modelModifiers: {}
+  }),
+  emits: /* @__PURE__ */ i(["change"], ["update:modelValue"]),
+  setup(o, { expose: m, emit: r }) {
+    const t = o, a = h(o, "modelValue"), c = r, { items: l, loading: d, error: u } = V(n(t, "dictType"), n(t, "dataSource"));
+    function p(e) {
+      a.value = e, c("change", e);
+    }
+    return m({ items: l, loading: d, error: u }), (e, v) => {
+      const f = b;
+      return g(), k(f, x({
+        "model-value": a.value,
+        items: s(l),
+        disabled: o.disabled || s(d)
+      }, e.$attrs, { "onUpdate:modelValue": p }), null, 16, ["model-value", "items", "disabled"]);
+    };
+  }
+});
+export {
+  B as _
+};

package/dist/SaberDictRadio.vue_vue_type_script_setup_true_lang-DR6-jSID.js

@@ -0,0 +1,50 @@
+import { defineComponent as c, useModel as f, openBlock as V, createBlock as g, mergeProps as _, mergeModels as m, toRef as r, unref as p } from "vue";
+import h from "@nuxt/ui/components/RadioGroup.vue";
+import { u as R } from "./use-dict-options-DjtbYYIa.js";
+const S = /* @__PURE__ */ c({
+  inheritAttrs: !1,
+  __name: "SaberRadioGroup",
+  props: {
+    modelValue: { default: void 0 },
+    modelModifiers: {}
+  },
+  emits: /* @__PURE__ */ m(["change"], ["update:modelValue"]),
+  setup(o, { emit: i }) {
+    const t = f(o, "modelValue"), a = i;
+    function l(e) {
+      t.value = e, a("change", e);
+    }
+    return (e, s) => {
+      const d = h;
+      return V(), g(d, _({ "model-value": t.value }, e.$attrs, { "onUpdate:modelValue": l }), null, 16, ["model-value"]);
+    };
+  }
+}), D = /* @__PURE__ */ c({
+  name: "SaberDictRadio",
+  inheritAttrs: !1,
+  __name: "SaberDictRadio",
+  props: /* @__PURE__ */ m({
+    dictType: {},
+    dataSource: { default: void 0 },
+    disabled: { type: Boolean, default: !1 }
+  }, {
+    modelValue: {},
+    modelModifiers: {}
+  }),
+  emits: /* @__PURE__ */ m(["change"], ["update:modelValue"]),
+  setup(o, { expose: i, emit: t }) {
+    const a = o, l = f(o, "modelValue"), e = t, { items: s, loading: d, error: b } = R(r(a, "dictType"), r(a, "dataSource"));
+    return i({ items: s, loading: d, error: b }), (v, n) => (V(), g(S, _({
+      modelValue: l.value,
+      "onUpdate:modelValue": n[0] || (n[0] = (u) => l.value = u),
+      items: p(s),
+      disabled: o.disabled || p(d)
+    }, v.$attrs, {
+      onChange: n[1] || (n[1] = (u) => e("change", u))
+    }), null, 16, ["modelValue", "items", "disabled"]));
+  }
+});
+export {
+  D as _,
+  S as a
+};

package/dist/SaberDictSelect.vue_vue_type_script_setup_true_lang-B8PTKNKX.js

@@ -0,0 +1,35 @@
+import { defineComponent as V, useModel as g, toRef as s, computed as h, openBlock as v, createBlock as S, mergeProps as y, unref as i, mergeModels as m } from "vue";
+import { _ as B } from "./SaberPopSelect.vue_vue_type_script_setup_true_lang-BcS27NXI.js";
+import { u as D } from "./use-dict-options-DjtbYYIa.js";
+const C = /* @__PURE__ */ V({
+  name: "SaberDictSelect",
+  inheritAttrs: !1,
+  __name: "SaberDictSelect",
+  props: /* @__PURE__ */ m({
+    dictType: {},
+    dataSource: { default: void 0 },
+    placeholder: { default: "请选择" },
+    clearable: { type: Boolean, default: !0 },
+    disabled: { type: Boolean, default: !1 }
+  }, {
+    modelValue: {},
+    modelModifiers: {}
+  }),
+  emits: /* @__PURE__ */ m(["change"], ["update:modelValue"]),
+  setup(e, { expose: n, emit: u }) {
+    const a = e, d = g(e, "modelValue"), c = u, { items: r, loading: o, error: p } = D(s(a, "dictType"), s(a, "dataSource")), f = h(() => o.value ? "加载中..." : a.placeholder);
+    return n({ items: r, loading: o, error: p }), (b, l) => (v(), S(B, y({
+      modelValue: d.value,
+      "onUpdate:modelValue": l[0] || (l[0] = (t) => d.value = t),
+      items: i(r),
+      placeholder: f.value,
+      clearable: e.clearable,
+      disabled: e.disabled || i(o)
+    }, b.$attrs, {
+      onChange: l[1] || (l[1] = (t) => c("change", t))
+    }), null, 16, ["modelValue", "items", "placeholder", "clearable", "disabled"]));
+  }
+});
+export {
+  C as _
+};