@kine-design/crud 0.0.1-beta.2 → 0.0.1-beta.21

package/dist/index.d.ts

@@ -8,10 +8,13 @@
  */
 export * from './components/layout';
 export { KSearchTable } from './components/searchTable';
+export { KCrudPage } from './components/crudPage';
 export { KLoginPage } from './components/login';
 export type { LoginForm } from './components/login';
 export { KPageHeader } from './components/pageHeader';
 export { defineRepository } from './composables/defineRepository';
+export { useCrudPage } from './composables/page';
+export type { CrudPageConfig, CrudColumnConfig, CrudFilterConfig, StatusMapItem } from './composables/page';
 export { setupCrud, createCrudApp, createQueryClient, useRequestClient, REQUEST_CLIENT_KEY } from './setup';
 export type { CrudOptions, CrudAppOptions, EnhancedApp } from './setup';
 export type { EntityId, ListParams, MutationOptions, Repository, RepositoryEndpoints, UseListReturn, UseDetailReturn, UseMutationReturn, } from './composables/types';
@@ -27,3 +30,11 @@ export { createRequest, createDefaultRequest, createStrictRequest, createPermiss
 export type { RequestMethod, ControlPolicy, CachePolicy, RetryPolicy, Lifecycle, RequestConfig, WrappedResponse, NetworkError, UserFeedbackHandler, Transport, TransportRequest, TransportResponse, RequestOptions, RequestClient, RequestBuilderContext, OrchestratorNode, FailureStrategy, OrchestratorResult, UploadOptions, UploaderOptions, UploadHandle, Uploader, UsePollingReturn, BatchLoaderOptions, UseBatchLoaderReturn, } from './composables/request';
 export { defineUserStore } from './composables/store';
 export type { UserStoreOptions, UserStore, LoginResult } from './composables/store';
+export { KFormCard, KStickyActionBar, KApprovalDialog, KFormPage, KMasterDetailPage } from './components/formPage';
+export type { ApprovalType } from './components/formPage';
+export { useFormPage } from './composables/form';
+export type { FormFieldType, FormFieldConfig, FormPageConfig, DetailTableConfig, MasterDetailPageConfig, UseFormPageOptions, UseFormPageReturn, } from './composables/form';
+export { KEditableTable } from './components/editableTable';
+export type { EditableColumn, EditableTableRow } from './components/editableTable';
+export { useAutoCompleteSearch } from './composables/search';
+export type { AutoCompleteSearchOptions, AutoCompleteSearchReturn } from './composables/search';

package/dist/setup.d.ts

@@ -1,4 +1,4 @@
-import { App, Component } from 'vue';
+import { App, Component, InjectionKey } from 'vue';
 import { QueryClient, VueQueryPluginOptions } from '@tanstack/vue-query';
 import { RequestOptions } from './composables/request/types';
 import { RequestClient } from './composables/request/createRequest';
@@ -42,7 +42,7 @@ export interface CrudAppOptions {
     query?: CrudOptions;
 }
 /** provide/inject 使用的唯一 symbol key */
-export declare const REQUEST_CLIENT_KEY: symbol;
+export declare const REQUEST_CLIENT_KEY: InjectionKey<RequestClient>;
 /**
  * 在组件中获取通过 createCrudApp 注入的 RequestClient。
  *

package/index.ts

@@ -0,0 +1,144 @@
+/**
+ * @description @kine-design/crud 入口
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export * from './components/layout';
+export { KSearchTable } from './components/searchTable';
+export { KCrudPage } from './components/crudPage';
+export { KLoginPage } from './components/login';
+export type { LoginForm } from './components/login';
+export { KPageHeader } from './components/pageHeader';
+export { defineRepository } from './composables/defineRepository';
+export { useCrudPage } from './composables/page';
+export type { CrudPageConfig, CrudColumnConfig, CrudFilterConfig, StatusMapItem } from './composables/page';
+export { setupCrud, createCrudApp, createQueryClient, useRequestClient, REQUEST_CLIENT_KEY } from './setup';
+export type { CrudOptions, CrudAppOptions, EnhancedApp } from './setup';
+export type {
+  EntityId,
+  ListParams,
+  MutationOptions,
+  Repository,
+  RepositoryEndpoints,
+  UseListReturn,
+  UseDetailReturn,
+  UseMutationReturn,
+} from './composables/types';
+
+export { KNavMenu } from './components/navMenu';
+export type { NavMenuData } from './components/navMenu';
+
+export { KUpload, KImageUpload, KFileList } from './components/upload';
+export type { UploadFile, UploadRequest } from './components/upload';
+
+export {
+  defineCrudRoutes,
+  createTabStore,
+  useTabStore,
+  useMenuFromRoutes,
+  createRouterGuard,
+  addTabFromRoute,
+} from './composables/router';
+export type {
+  CrudRouteMeta,
+  CrudRouteConfig,
+  CrudRouteRecord,
+  TabItem,
+  TabStore,
+  RouteLocationLike,
+  RouterGuard,
+  RouterGuardOptions,
+} from './composables/router';
+
+export {
+  createAuth,
+  useAuth,
+  createAuthGuard,
+  createVCan,
+} from './composables/auth';
+export type {
+  Permission,
+  PermissionScope,
+  UserInfo,
+  AuthState,
+  AuthOptions,
+  AuthReturn,
+  AuthGuardOptions,
+  BeforeEachGuard,
+  CanBinding,
+  CanBindingObject,
+} from './composables/auth';
+
+export {
+  createRequest,
+  createDefaultRequest,
+  createStrictRequest,
+  createPermissiveRequest,
+  createUploader,
+  useRequest,
+  usePolling,
+  useBatchLoader,
+  orchestrate,
+  createNode,
+  after,
+  BusinessError,
+  NetworkRequestError,
+  ControlGate,
+  FetchTransport,
+  XhrTransport,
+  RequestBuilder,
+} from './composables/request';
+export type {
+  RequestMethod,
+  ControlPolicy,
+  CachePolicy,
+  RetryPolicy,
+  Lifecycle,
+  RequestConfig,
+  WrappedResponse,
+  NetworkError,
+  UserFeedbackHandler,
+  Transport,
+  TransportRequest,
+  TransportResponse,
+  RequestOptions,
+  RequestClient,
+  RequestBuilderContext,
+  OrchestratorNode,
+  FailureStrategy,
+  OrchestratorResult,
+  UploadOptions,
+  UploaderOptions,
+  UploadHandle,
+  Uploader,
+  UsePollingReturn,
+  BatchLoaderOptions,
+  UseBatchLoaderReturn,
+} from './composables/request';
+
+export { defineUserStore } from './composables/store';
+export type { UserStoreOptions, UserStore, LoginResult } from './composables/store';
+
+export { KFormCard, KStickyActionBar, KApprovalDialog, KFormPage, KMasterDetailPage } from './components/formPage';
+export type { ApprovalType } from './components/formPage';
+
+export { useFormPage } from './composables/form';
+export type {
+  FormFieldType,
+  FormFieldConfig,
+  FormPageConfig,
+  DetailTableConfig,
+  MasterDetailPageConfig,
+  UseFormPageOptions,
+  UseFormPageReturn,
+} from './composables/form';
+
+export { KEditableTable } from './components/editableTable';
+export type { EditableColumn, EditableTableRow } from './components/editableTable';
+
+export { useAutoCompleteSearch } from './composables/search';
+export type { AutoCompleteSearchOptions, AutoCompleteSearchReturn } from './composables/search';

package/package.json

@@ -1,33 +1,34 @@
 {
   "name": "@kine-design/crud",
-  "version": "0.0.1-beta.2",
+  "version": "0.0.1-beta.21",
   "type": "module",
   "main": "./dist/crud.js",
-  "module": "./dist/crud.js",
   "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/crud.js"
-      }
-    }
-  },
-  "files": [
-    "dist"
-  ],
   "dependencies": {
-    "@kine-design/core": "0.0.1-beta.1",
-    "@tanstack/vue-query": "^5.92.9",
-    "kine-ui": "0.0.1-beta.1",
+    "@tanstack/vue-query": "^5.92.10",
     "pinia": "^3.0.3",
-    "vue": "^3.4.0",
-    "vue-router": "^4.6.4"
+    "vue": "^3.5.30",
+    "vue-router": "^5.0.3",
+    "@kine-design/core": "0.0.1-beta.6",
+    "kine-ui": "0.0.1-beta.12"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "files": [
+      "dist"
+    ]
   },
   "scripts": {
     "build": "vite build --config vite.config.build.ts"
+  },
+  "module": "./dist/crud.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/crud.js"
+      }
+    },
+    "./dist/crud.css": "./dist/crud.css"
   }
 }

package/setup.ts

@@ -0,0 +1,288 @@
+/**
+ * @description CRUD 基础设施安装函数，在 main.ts 调用一次即可
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { createApp as vueCreateApp, inject, type App, type Component, type InjectionKey } from 'vue';
+import {
+  VueQueryPlugin,
+  QueryClient,
+  type VueQueryPluginOptions,
+} from '@tanstack/vue-query';
+import { createPinia } from 'pinia';
+import type { AuthReturn } from './composables/auth/types';
+import type { RequestOptions } from './composables/request/types';
+import type { RequestClient } from './composables/request/createRequest';
+import type { ErrorHandlerOptions } from './composables/error/types';
+import { createAuth } from './composables/auth/useAuth';
+import { createAuthGuard, type BeforeEachGuard } from './composables/auth/authGuard';
+import { createVCan } from './composables/auth/vCan';
+import { createRequest } from './composables/request/createRequest';
+import { createErrorHandler } from './composables/error/createErrorHandler';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 局部 vue-router 类型声明（不引入 vue-router 依赖）
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 最小化 Router 接口，只声明本文件用到的方法 */
+interface RouterLike {
+  beforeEach(guard: BeforeEachGuard): void;
+  install(app: App): void;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// CrudOptions — TanStack Query 配置
+// ────────────────────────────────────────────────────────────────────────────
+
+/** setupCrud / createCrudApp 的配置选项 */
+export interface CrudOptions {
+  /**
+   * 自定义 QueryClient 实例。
+   * 不传时内部自动创建，使用合理的默认配置。
+   */
+  queryClient?: QueryClient;
+  /** 透传给 VueQueryPlugin 的其余选项（queryClient 字段会被覆盖）。 */
+  vueQueryOptions?: Omit<VueQueryPluginOptions, 'queryClient'>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// CrudAppOptions — 一站式初始化配置
+// ────────────────────────────────────────────────────────────────────────────
+
+/** createCrudApp 高级版本的完整配置 */
+export interface CrudAppOptions {
+  /** Vue Router 实例 */
+  router?: RouterLike;
+  /** Auth 配置（传入后自动 createAuth + createAuthGuard + v-can 指令） */
+  auth?: {
+    fetchUser: () => Promise<{ user: import('./composables/auth/types').UserInfo; permissions: import('./composables/auth/types').Permission[]; token: string }>;
+    onUnauthorized?: () => void;
+    storage?: 'local' | 'session' | false;
+    loginPath?: string;
+  };
+  /** Request 配置（传入后自动 createRequest 并挂载到 app.provide） */
+  request?: RequestOptions;
+  /** 错误处理配置 */
+  error?: ErrorHandlerOptions;
+  /** TanStack Query 配置 */
+  query?: CrudOptions;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// REQUEST_CLIENT_KEY + useRequestClient
+// ────────────────────────────────────────────────────────────────────────────
+
+/** provide/inject 使用的唯一 symbol key */
+export const REQUEST_CLIENT_KEY: InjectionKey<RequestClient> = Symbol('kine-design:request');
+
+/**
+ * 在组件中获取通过 createCrudApp 注入的 RequestClient。
+ *
+ * @throws 若未在 createCrudApp 中配置 request 选项，抛出错误。
+ */
+export function useRequestClient(): RequestClient {
+  const client = inject(REQUEST_CLIENT_KEY);
+  if (!client) {
+    throw new Error('[useRequestClient] 未找到 RequestClient，请在 createCrudApp 中配置 request 选项。');
+  }
+  return client;
+}
+
+/**
+ * 创建一个预配置好的 QueryClient 实例（供高级场景直接使用）。
+ */
+export function createQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        // 窗口重新聚焦时不自动重新请求，业务层按需覆盖
+        refetchOnWindowFocus: false,
+        // 失败后重试 1 次
+        retry: 1,
+        // 数据保鲜时间 1 分钟
+        staleTime: 1000 * 60,
+      },
+    },
+  });
+}
+
+/**
+ * 在 Vue App 实例上安装 CRUD 基础设施（TanStack Query）。
+ * 推荐在 main.ts 调用一次，业务代码无需再关心 TanStack Query 安装细节。
+ *
+ * @example
+ * ```ts
+ * // main.ts
+ * import { createApp } from 'vue';
+ * import { setupCrud } from '@kine-design/crud/setup';
+ *
+ * const app = createApp(App);
+ * setupCrud(app);
+ * app.mount('#app');
+ * ```
+ */
+export function setupCrud(app: App, options?: CrudOptions): void {
+  const queryClient = options?.queryClient ?? createQueryClient();
+
+  app.use(VueQueryPlugin, {
+    queryClient,
+    ...options?.vueQueryOptions,
+  });
+
+  // 自动安装 Pinia（若尚未安装）
+  installPinia(app);
+}
+
+/**
+ * 安装 Pinia 到 Vue App。
+ * 通过检查 app._context.provides 中是否已存在 Pinia 的 symbol 来避免重复安装。
+ */
+function installPinia(app: App): void {
+  // Pinia 安装后会在 provides 中注入一个 symbol key，
+  // 检查 provides 中是否已有 Pinia 实例（其 _a 属性指向 app）
+  const provides = (app as { _context: { provides: Record<symbol, unknown> } })._context.provides;
+  const hasPinia = Object.getOwnPropertySymbols(provides).some(sym => {
+    const val = provides[sym];
+    return val !== null && typeof val === 'object' && '_a' in (val as Record<string, unknown>);
+  });
+  if (!hasPinia) {
+    app.use(createPinia());
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// EnhancedApp — mount 前自动恢复 auth 状态
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 增强的 App 接口，mount 时自动恢复 auth 状态 */
+export interface EnhancedApp extends Omit<App, 'mount'> {
+  mount(rootContainer: string | Element): App;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// createCrudApp — 两种签名
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * createCrudApp — 链式风格的工厂函数，等同于 createApp + setupCrud。
+ *
+ * @example
+ * ```ts
+ * // 基础用法
+ * createCrudApp(App).mount('#app');
+ *
+ * // 高级用法：一站式初始化
+ * createCrudApp(App, {
+ *   router,
+ *   auth: { fetchUser, onUnauthorized: () => router.push('/login'), storage: 'local' },
+ *   request: { baseURL: '/api' },
+ *   error: { unauthorizedStrategy: 'redirect' },
+ * }).mount('#app');
+ * ```
+ */
+export function createCrudApp(
+  rootComponent: Component,
+  rootProps?: Record<string, unknown>,
+  options?: CrudOptions,
+): App;
+export function createCrudApp(
+  rootComponent: Component,
+  options: CrudAppOptions,
+): EnhancedApp;
+export function createCrudApp(
+  rootComponent: Component,
+  rootPropsOrOptions?: Record<string, unknown> | CrudAppOptions,
+  crudOptions?: CrudOptions,
+): App | EnhancedApp {
+  // 判断第二个参数是 CrudAppOptions 还是 rootProps
+  if (rootPropsOrOptions && isCrudAppOptions(rootPropsOrOptions)) {
+    return createCrudAppWithOptions(rootComponent, rootPropsOrOptions as CrudAppOptions);
+  }
+
+  // 原有逻辑：createCrudApp(rootComponent, rootProps?, crudOptions?)
+  const app = vueCreateApp(rootComponent, rootPropsOrOptions as Record<string, unknown> | undefined);
+  setupCrud(app, crudOptions);
+  return app;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部：判断是否为 CrudAppOptions
+// ────────────────────────────────────────────────────────────────────────────
+
+function isCrudAppOptions(obj: Record<string, unknown> | CrudAppOptions): boolean {
+  return 'router' in obj || 'auth' in obj || 'request' in obj || 'error' in obj || 'query' in obj;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部：高级版本实现
+// ────────────────────────────────────────────────────────────────────────────
+
+function createCrudAppWithOptions(
+  rootComponent: Component,
+  options: CrudAppOptions,
+): EnhancedApp {
+  const app = vueCreateApp(rootComponent);
+
+  // 1. Auth（必须在 Router 安装前创建，否则初始导航绕过守卫）
+  let auth: AuthReturn | undefined;
+  if (options.auth) {
+    auth = createAuth(app, {
+      fetchUser: options.auth.fetchUser,
+      onUnauthorized: options.auth.onUnauthorized,
+      storage: options.auth.storage,
+    });
+    // v-can 指令
+    app.directive('can', createVCan(auth));
+    // 路由守卫：注册在 router 实例上（不依赖 app.use），确保 install 触发初始导航时守卫已就位
+    if (options.router) {
+      const guard = createAuthGuard(auth, { loginPath: options.auth.loginPath ?? '/login' });
+      options.router.beforeEach(guard);
+    }
+  }
+
+  // 2. Router（install 时触发初始导航，此时守卫已注册）
+  if (options.router) {
+    app.use(options.router as { install: (app: App) => void });
+  }
+
+  // 3. TanStack Query
+  setupCrud(app, options.query);
+
+  // 4. Request
+  if (options.request) {
+    const requestOptions: RequestOptions = { ...options.request };
+    // 如果有 auth，自动注入 getToken
+    if (auth && !requestOptions.getToken) {
+      requestOptions.getToken = () => auth!.token.value;
+    }
+    // 如果有 auth，自动注入 onUnauthorized
+    if (auth && !requestOptions.onUnauthorized) {
+      requestOptions.onUnauthorized = options.auth?.onUnauthorized;
+    }
+    const client = createRequest(requestOptions);
+    app.provide(REQUEST_CLIENT_KEY, client);
+  }
+
+  // 5. Error Handler
+  if (options.error) {
+    createErrorHandler(app, options.error);
+  }
+
+  // 返回增强的 app，mount 前先恢复 auth
+  const enhancedApp: EnhancedApp = Object.create(app);
+  enhancedApp.mount = (rootContainer: string | Element): App => {
+    const doMount = () => app.mount(rootContainer);
+    if (auth) {
+      auth.restore().finally(doMount);
+    } else {
+      doMount();
+    }
+    return app;
+  };
+
+  return enhancedApp;
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "noEmit": true
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.d.ts"
+  ]
+}

package/vite.config.build.ts

@@ -0,0 +1,52 @@
+/**
+ * @description @kine-design/crud 构建配置
+ * @author 阿怪
+ * @date 2026/3/16
+ * @version v1.0.0
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+import { defineConfig } from 'vite';
+import Jsx from '@vitejs/plugin-vue-jsx';
+import dts from 'vite-plugin-dts';
+import path from 'path';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@kine-design/core': path.resolve(__dirname, '../core'),
+    },
+  },
+  build: {
+    outDir: 'dist',
+    emptyOutDir: true,
+    minify: false,
+    lib: {
+      entry: path.resolve(__dirname, 'index.ts'),
+      name: 'KineCrud',
+      fileName: 'crud',
+      formats: ['es'],
+    },
+    rolldownOptions: {
+      external: [
+        'vue',
+        'vue-router',
+        'pinia',
+        '@tanstack/vue-query',
+        'kine-ui',
+      ],
+      output: {
+        assetFileNames: 'crud.[ext]',
+      },
+    },
+  },
+  plugins: [
+    Jsx(),
+    dts({
+      include: ['./**/*.ts', './**/*.tsx'],
+      exclude: ['node_modules'],
+      outDir: 'dist',
+      tsconfigPath: './tsconfig.json',
+    }),
+  ],
+});