@svadmin/core 0.16.0 → 0.17.1

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@svadmin/core",
-  "version": "0.16.0",
-  "description": "Core SDK — hooks, types, context, i18n, permissions, router",
-  "type": "module",
-  "sideEffects": false,
-  "files": [
-    "src/**/*"
-  ],
+  "version": "0.17.1",
+  "author": "zuohuadong",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zuohuadong/svadmin.git",
+    "directory": "packages/core"
+  },
   "main": "src/index.ts",
-  "types": "src/index.ts",
+  "devDependencies": {
+    "@types/bun": "^1.3.11"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0",
+    "@tanstack/svelte-query": "^6.0.0"
+  },
   "exports": {
     ".": {
       "types": "./src/index.ts",
@@ -43,25 +49,19 @@
       "default": "./src/theme.svelte.ts"
     }
   },
-  "peerDependencies": {
-    "svelte": "^5.0.0",
-    "@tanstack/svelte-query": "^6.0.0"
-  },
-  "license": "MIT",
-  "author": "zuohuadong",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/zuohuadong/svadmin.git",
-    "directory": "packages/core"
-  },
-  "homepage": "https://github.com/zuohuadong/svadmin#readme",
   "bugs": {
     "url": "https://github.com/zuohuadong/svadmin/issues"
   },
-  "devDependencies": {
-    "@types/bun": "^1.3.11"
-  },
+  "description": "Core SDK — hooks, types, context, i18n, permissions, router",
+  "files": [
+    "src/**/*"
+  ],
+  "homepage": "https://github.com/zuohuadong/svadmin#readme",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "types": "src/index.ts",
   "dependencies": {
-    "svelte-sonner": "^1.1.0"
+    "sonner-svelte": "^0.3.3"
   }
 }

package/src/README.md

@@ -0,0 +1,18 @@
+# Name
+### {{module_name}}
+
+# Synopsis
+{{synopsis}}
+
+# Description
+
+# Example
+
+# Install:
+`npm install {{module_name}}`
+
+# Test:
+`npm test`
+
+#License:
+{{license}}

package/src/chatProvider.svelte.ts

@@ -1,4 +1,10 @@
-// Chat provider — headless interface for AI chat integration
+// Chat & Agent provider — headless interface for AI integration
+//
+// Two abstraction levels:
+//   1. ChatProvider  — simple message-in / text-out  (backward compatible)
+//   2. AgentProvider — tool calling, approval gates, generative UI events
+//
+// Inspired by Vercel AI SDK 6 agent abstractions.
 
 /** Describes an actionable button rendered in assistant messages (tool-call UX). */
 export interface ChatAction {
@@ -40,6 +46,117 @@ export interface ChatProvider {
   ): Promise<string> | AsyncGenerator<string, void, unknown>;
 }
 
+// ─── Agent Provider (extends ChatProvider concept) ─────────────
+//
+// An AgentProvider emits typed events instead of raw strings, enabling:
+//   • Tool calling — Agent invokes admin operations (CRUD, custom)
+//   • Approval gates — Dangerous tools require user confirmation before execution
+//   • Generative UI — Agent returns component name + props for dynamic rendering
+
+/** JSON-Schema-compatible parameter definition for an admin tool. */
+export interface AdminToolParameter {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description?: string;
+  enum?: string[];
+  required?: boolean;
+}
+
+/**
+ * A tool that the Agent can invoke within the admin panel.
+ *
+ * @example
+ * ```ts
+ * const deletePostTool: AdminTool = {
+ *   name: 'deletePosts',
+ *   description: 'Delete posts matching a filter',
+ *   parameters: {
+ *     status: { type: 'string', description: 'Filter by status', enum: ['draft', 'archived'] },
+ *   },
+ *   needsApproval: true,
+ *   execute: async (params) => {
+ *     const result = await dataProvider.deleteMany({ resource: 'posts', ids: params.ids });
+ *     return { success: true, data: result };
+ *   },
+ * };
+ * ```
+ */
+export interface AdminTool {
+  /** Unique tool name (e.g. 'getList', 'deleteRecords', 'generateReport') */
+  name: string;
+  /** Human-readable description for LLM tool-use prompting */
+  description: string;
+  /** JSON-Schema-style parameter definitions */
+  parameters: Record<string, AdminToolParameter>;
+  /**
+   * When `true`, execution is paused until the user explicitly approves.
+   * The agent emits an `approval_request` event and waits for `approveToolCall()`.
+   */
+  needsApproval?: boolean;
+  /** Execute the tool with the given arguments. */
+  execute(args: Record<string, unknown>): Promise<ToolResult>;
+}
+
+/** Result returned by a tool execution. */
+export interface ToolResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+}
+
+/** Discriminated union of events emitted by an AgentProvider. */
+export type AgentEvent =
+  /** Streaming text chunk */
+  | { type: 'text'; content: string }
+  /** Agent wants to call a tool (informational — execution is handled internally) */
+  | { type: 'tool_call'; tool: string; args: Record<string, unknown> }
+  /** Agent wants to call a tool that requires user approval before execution */
+  | { type: 'approval_request'; id: string; tool: string; args: Record<string, unknown>; description: string }
+  /** Tool execution completed */
+  | { type: 'tool_result'; tool: string; result: ToolResult }
+  /** Agent wants to render a named component (Generative UI) */
+  | { type: 'component'; name: string; props: Record<string, unknown> }
+  /** Stream finished */
+  | { type: 'done' };
+
+/** Options passed to AgentProvider.chat() */
+export interface AgentOptions {
+  signal?: AbortSignal;
+  /** Admin context is injected automatically by the framework */
+  context?: ChatContext;
+}
+
+/**
+ * AgentProvider — advanced AI integration with tool calling and approval gates.
+ *
+ * Implement this interface to connect to agentic AI backends that support
+ * function calling (OpenAI, Anthropic, Google Gemini, etc.).
+ *
+ * For simpler chat-only use cases, use `ChatProvider` instead.
+ *
+ * @example
+ * ```ts
+ * const agentProvider: AgentProvider = {
+ *   tools: [deletePostTool, getStatsTool],
+ *   async *chat(messages, options) {
+ *     // Stream events from your AI backend
+ *     yield { type: 'text', content: 'Looking up draft posts...' };
+ *     yield { type: 'tool_call', tool: 'getList', args: { resource: 'posts', filter: { status: 'draft' } } };
+ *     yield { type: 'approval_request', id: 'req-1', tool: 'deletePosts', args: { ids: ['1', '2'] }, description: 'Delete 2 draft posts' };
+ *     yield { type: 'done' };
+ *   },
+ * };
+ * ```
+ */
+export interface AgentProvider {
+  /** Available tools the agent can invoke */
+  tools?: AdminTool[];
+  /** Send messages and receive a stream of typed agent events */
+  chat(
+    messages: ChatMessage[],
+    options?: AgentOptions,
+  ): AsyncGenerator<AgentEvent, void, unknown>;
+}
+
 // ─── Chat Provider singleton ───────────────────────────────────
 
 let chatProvider: ChatProvider | null = $state(null);
@@ -52,6 +169,53 @@ export function getChatProvider(): ChatProvider | null {
   return chatProvider;
 }
 
+// ─── Agent Provider singleton ──────────────────────────────────
+
+let agentProvider: AgentProvider | null = $state(null);
+
+export function setAgentProvider(provider: AgentProvider): void {
+  agentProvider = provider;
+}
+
+export function getAgentProvider(): AgentProvider | null {
+  return agentProvider;
+}
+
+// ─── Tool Approval ─────────────────────────────────────────────
+
+type ApprovalCallback = (approved: boolean) => void;
+const pendingApprovals = new Map<string, ApprovalCallback>();
+
+/**
+ * Register a pending approval request. Called internally by the framework
+ * when an `approval_request` event is received from the agent.
+ */
+export function registerApproval(id: string, callback: ApprovalCallback): void {
+  pendingApprovals.set(id, callback);
+}
+
+/**
+ * Approve or reject a pending tool call.
+ *
+ * @example
+ * ```svelte
+ * <button onclick={() => resolveApproval('req-1', true)}>Approve</button>
+ * <button onclick={() => resolveApproval('req-1', false)}>Reject</button>
+ * ```
+ */
+export function resolveApproval(id: string, approved: boolean): boolean {
+  const cb = pendingApprovals.get(id);
+  if (!cb) return false;
+  cb(approved);
+  pendingApprovals.delete(id);
+  return true;
+}
+
+/** Check if there are any pending approval requests. */
+export function hasPendingApprovals(): boolean {
+  return pendingApprovals.size > 0;
+}
+
 // ─── Chat Context singleton ────────────────────────────────────
 
 let chatContext = $state<ChatContext>({});

package/src/chatProvider.test.ts

@@ -166,3 +166,223 @@ describe('localStorage persistence simulation', () => {
     expect(restored[1].actions![0].label).toBe('Create Post');
   });
 });
+
+// ─── AgentProvider Types ───────────────────────────────────────
+
+/** Mirror of AdminToolParameter from chatProvider.svelte.ts */
+interface AdminToolParameter {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description?: string;
+  enum?: string[];
+  required?: boolean;
+}
+
+/** Mirror of AdminTool from chatProvider.svelte.ts */
+interface AdminTool {
+  name: string;
+  description: string;
+  parameters: Record<string, AdminToolParameter>;
+  needsApproval?: boolean;
+  execute(args: Record<string, unknown>): Promise<{ success: boolean; data?: unknown; error?: string }>;
+}
+
+/** Mirror of AgentEvent from chatProvider.svelte.ts */
+type AgentEvent =
+  | { type: 'text'; content: string }
+  | { type: 'tool_call'; tool: string; args: Record<string, unknown> }
+  | { type: 'approval_request'; id: string; tool: string; args: Record<string, unknown>; description: string }
+  | { type: 'tool_result'; tool: string; result: { success: boolean; data?: unknown; error?: string } }
+  | { type: 'component'; name: string; props: Record<string, unknown> }
+  | { type: 'done' };
+
+describe('AdminTool shape', () => {
+  test('tool with needsApproval serializes correctly', () => {
+    const tool: AdminTool = {
+      name: 'deletePosts',
+      description: 'Delete posts matching a filter',
+      parameters: {
+        status: { type: 'string', description: 'Filter by status', enum: ['draft', 'archived'] },
+      },
+      needsApproval: true,
+      execute: async (args) => ({ success: true, data: { deleted: args.ids } }),
+    };
+
+    expect(tool.name).toBe('deletePosts');
+    expect(tool.needsApproval).toBe(true);
+    expect(tool.parameters.status.enum).toEqual(['draft', 'archived']);
+  });
+
+  test('tool without approval defaults to undefined', () => {
+    const tool: AdminTool = {
+      name: 'getStats',
+      description: 'Fetch dashboard statistics',
+      parameters: {},
+      execute: async () => ({ success: true, data: { users: 100 } }),
+    };
+
+    expect(tool.needsApproval).toBeUndefined();
+  });
+
+  test('tool execute returns ToolResult', async () => {
+    const tool: AdminTool = {
+      name: 'createPost',
+      description: 'Create a new post',
+      parameters: {
+        title: { type: 'string', required: true },
+      },
+      execute: async (args) => ({
+        success: true,
+        data: { id: '1', title: args.title },
+      }),
+    };
+
+    const result = await tool.execute({ title: 'Hello World' });
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual({ id: '1', title: 'Hello World' });
+  });
+
+  test('tool execute can return error', async () => {
+    const tool: AdminTool = {
+      name: 'failingTool',
+      description: 'A tool that fails',
+      parameters: {},
+      execute: async () => ({
+        success: false,
+        error: 'Permission denied',
+      }),
+    };
+
+    const result = await tool.execute({});
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Permission denied');
+  });
+});
+
+describe('AgentEvent stream', () => {
+  test('events can be collected from async generator', async () => {
+    async function* mockAgent(): AsyncGenerator<AgentEvent, void, unknown> {
+      yield { type: 'text', content: 'Searching...' };
+      yield { type: 'tool_call', tool: 'getList', args: { resource: 'posts' } };
+      yield { type: 'tool_result', tool: 'getList', result: { success: true, data: [{ id: 1 }] } };
+      yield { type: 'text', content: 'Found 1 post.' };
+      yield { type: 'done' };
+    }
+
+    const events: AgentEvent[] = [];
+    for await (const event of mockAgent()) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(5);
+    expect(events[0].type).toBe('text');
+    expect(events[1].type).toBe('tool_call');
+    expect(events[2].type).toBe('tool_result');
+    expect(events[4].type).toBe('done');
+  });
+
+  test('approval_request event serializes correctly', () => {
+    const event: AgentEvent = {
+      type: 'approval_request',
+      id: 'req-42',
+      tool: 'deletePosts',
+      args: { ids: ['1', '2', '3'] },
+      description: 'Delete 3 draft posts',
+    };
+
+    const serialized = JSON.stringify(event);
+    const parsed = JSON.parse(serialized) as AgentEvent;
+
+    expect(parsed.type).toBe('approval_request');
+    if (parsed.type === 'approval_request') {
+      expect(parsed.id).toBe('req-42');
+      expect(parsed.tool).toBe('deletePosts');
+      expect(parsed.description).toBe('Delete 3 draft posts');
+    }
+  });
+
+  test('component event carries name and props', () => {
+    const event: AgentEvent = {
+      type: 'component',
+      name: 'SalesChart',
+      props: { period: 'monthly', data: [100, 200, 150] },
+    };
+
+    expect(event.type).toBe('component');
+    if (event.type === 'component') {
+      expect(event.name).toBe('SalesChart');
+      expect(event.props.period).toBe('monthly');
+    }
+  });
+});
+
+describe('Approval flow', () => {
+  test('registerApproval and resolveApproval work together', () => {
+    // Simulate the approval flow without importing rune-based module
+    const pending = new Map<string, (approved: boolean) => void>();
+
+    function register(id: string, cb: (approved: boolean) => void) {
+      pending.set(id, cb);
+    }
+
+    function resolve(id: string, approved: boolean): boolean {
+      const cb = pending.get(id);
+      if (!cb) return false;
+      cb(approved);
+      pending.delete(id);
+      return true;
+    }
+
+    let approvalResult = false;
+
+    register('req-1', (approved) => {
+      approvalResult = approved;
+    });
+
+    expect(pending.size).toBe(1);
+
+    // Resolve with approval
+    const resolved = resolve('req-1', true);
+    expect(resolved).toBe(true);
+    expect(approvalResult).toEqual(true);
+    expect(pending.size).toBe(0);
+  });
+
+  test('resolveApproval returns false for unknown id', () => {
+    const pending = new Map<string, (approved: boolean) => void>();
+
+    function resolve(id: string, approved: boolean): boolean {
+      const cb = pending.get(id);
+      if (!cb) return false;
+      cb(approved);
+      pending.delete(id);
+      return true;
+    }
+
+    expect(resolve('nonexistent', true)).toBe(false);
+  });
+
+  test('rejection flow works', () => {
+    const pending = new Map<string, (approved: boolean) => void>();
+
+    function register(id: string, cb: (approved: boolean) => void) {
+      pending.set(id, cb);
+    }
+
+    function resolve(id: string, approved: boolean): boolean {
+      const cb = pending.get(id);
+      if (!cb) return false;
+      cb(approved);
+      pending.delete(id);
+      return true;
+    }
+
+    let wasApproved = true;
+
+    register('req-2', (approved) => {
+      wasApproved = approved;
+    });
+
+    resolve('req-2', false);
+    expect(wasApproved).toEqual(false);
+  });
+});

package/src/i18n.svelte.ts

@@ -184,6 +184,51 @@ const locales: Record<string, Locale> = {
     'settings.auditIp': 'IP 地址',
     'settings.auditTotal': '条记录',
     'settings.auditSnapshot': '变更快照',
+    // Editor
+    'editor.bold': '加粗',
+    'editor.italic': '斜体',
+    'editor.underline': '下划线',
+    'editor.strikethrough': '删除线',
+    'editor.code': '行内代码',
+    'editor.codeBlock': '代码块',
+    'editor.h1': '一级标题',
+    'editor.h2': '二级标题',
+    'editor.h3': '三级标题',
+    'editor.h4': '四级标题',
+    'editor.bulletList': '无序列表',
+    'editor.orderedList': '有序列表',
+    'editor.taskList': '任务列表',
+    'editor.blockquote': '引用',
+    'editor.alignLeft': '左对齐',
+    'editor.alignCenter': '居中对齐',
+    'editor.alignRight': '右对齐',
+    'editor.alignJustify': '两端对齐',
+    'editor.link': '插入链接',
+    'editor.image': '插入图片',
+    'editor.table': '插入表格',
+    'editor.color': '文本颜色',
+    'editor.highlight': '高亮',
+    'editor.clearFormat': '清除格式',
+    'editor.undo': '撤销',
+    'editor.redo': '重做',
+    'editor.startWriting': '开始写作...',
+    'editor.typeSlash': '输入 / 唤出菜单',
+    // Editor - Popovers
+    'editor.link.url': '链接地址',
+    'editor.link.openInNewTab': '在新标签页打开',
+    'editor.link.apply': '应用',
+    'editor.link.remove': '移除链接',
+    'editor.image.url': '图片链接 (URL)',
+    'editor.image.upload': '点击或拖拽图片到此处上传',
+    'editor.image.uploading': '上传中...',
+    'editor.table.insertRowAbove': '在上方插入行',
+    'editor.table.insertRowBelow': '在下方插入行',
+    'editor.table.deleteRow': '删除行',
+    'editor.table.insertColumnLeft': '在左侧插入列',
+    'editor.table.insertColumnRight': '在右侧插入列',
+    'editor.table.deleteColumn': '删除列',
+    'editor.table.deleteTable': '删除表格',
+    'editor.table.mergeCells': '合并/拆分单元格',
     // Profile
     'profile.title': '个人资料',
     'profile.name': '姓名',
@@ -374,6 +419,51 @@ const locales: Record<string, Locale> = {
     'settings.auditIp': 'IP Address',
     'settings.auditTotal': 'total records',
     'settings.auditSnapshot': 'Change Snapshot',
+    // Editor
+    'editor.bold': 'Bold',
+    'editor.italic': 'Italic',
+    'editor.underline': 'Underline',
+    'editor.strikethrough': 'Strikethrough',
+    'editor.code': 'Inline Code',
+    'editor.codeBlock': 'Code Block',
+    'editor.h1': 'Heading 1',
+    'editor.h2': 'Heading 2',
+    'editor.h3': 'Heading 3',
+    'editor.h4': 'Heading 4',
+    'editor.bulletList': 'Bullet List',
+    'editor.orderedList': 'Ordered List',
+    'editor.taskList': 'Task List',
+    'editor.blockquote': 'Blockquote',
+    'editor.alignLeft': 'Align Left',
+    'editor.alignCenter': 'Align Center',
+    'editor.alignRight': 'Align Right',
+    'editor.alignJustify': 'Justify',
+    'editor.link': 'Insert Link',
+    'editor.image': 'Insert Image',
+    'editor.table': 'Insert Table',
+    'editor.color': 'Text Color',
+    'editor.highlight': 'Highlight',
+    'editor.clearFormat': 'Clear Formatting',
+    'editor.undo': 'Undo',
+    'editor.redo': 'Redo',
+    'editor.startWriting': 'Start writing...',
+    'editor.typeSlash': 'Type / for commands',
+    // Editor - Popovers
+    'editor.link.url': 'Link URL',
+    'editor.link.openInNewTab': 'Open in new tab',
+    'editor.link.apply': 'Apply',
+    'editor.link.remove': 'Remove Link',
+    'editor.image.url': 'Image URL',
+    'editor.image.upload': 'Click or drag image here to upload',
+    'editor.image.uploading': 'Uploading...',
+    'editor.table.insertRowAbove': 'Insert row above',
+    'editor.table.insertRowBelow': 'Insert row below',
+    'editor.table.deleteRow': 'Delete row',
+    'editor.table.insertColumnLeft': 'Insert column left',
+    'editor.table.insertColumnRight': 'Insert column right',
+    'editor.table.deleteColumn': 'Delete column',
+    'editor.table.deleteTable': 'Delete table',
+    'editor.table.mergeCells': 'Toggle merge cells',
     // Profile
     'profile.title': 'Profile',
     'profile.name': 'Name',

package/src/index.ts

@@ -34,8 +34,8 @@ export { notify, closeNotification, setNotificationProvider, getNotificationProv
 export { t, setLocale, getLocale, getAvailableLocales, addTranslations, useTranslation } from './i18n.svelte';
 export { audit, setAuditHandler, setAuditLogProvider, getAuditLogProvider } from './audit';
 export type { AuditLogProvider } from './audit';
-export { setChatProvider, getChatProvider, setChatContext, getChatContext } from './chatProvider.svelte';
-export type { ChatProvider, ChatMessage, ChatContext, ChatAction } from './chatProvider.svelte';
+export { setChatProvider, getChatProvider, setChatContext, getChatContext, setAgentProvider, getAgentProvider, registerApproval, resolveApproval, hasPendingApprovals } from './chatProvider.svelte';
+export type { ChatProvider, ChatMessage, ChatContext, ChatAction, AgentProvider, AgentEvent, AgentOptions, AdminTool, AdminToolParameter, ToolResult } from './chatProvider.svelte';
 export { getTheme, setTheme, toggleTheme, getResolvedTheme, getColorTheme, setColorTheme, colorThemes, configureTheme, getThemeConfig, clearCssOverrides, builtinPresets, registerColorPreset, getColorPresets } from './theme.svelte';
 export type { ThemeMode, ColorTheme, ThemeStrategy, ThemeConfig, ColorPreset } from './theme.svelte';
 export { setUnsavedChanges, getUnsavedChanges, initUnsavedChangesNotifier } from './unsaved-changes.svelte';

package/src/toast.svelte.ts

@@ -1,7 +1,7 @@
-// Toast notification system — wraps svelte-sonner for consistent API
+// Toast notification system — wraps sonner-svelte for consistent API
 // Maintains backward-compatible `toast.success()` / `toast.error()` etc.
 
-import { toast as sonner } from 'svelte-sonner';
+import { toast as sonner } from 'sonner-svelte';
 
 export type ToastType = 'success' | 'error' | 'info' | 'warning' | 'undoable';
 
@@ -23,7 +23,7 @@ export function getToasts(): Toast[] {
 }
 
 export function addToast(type: ToastType, message: string, duration = 3000, options?: { onUndo?: () => void, onTimeout?: () => void }): void {
-  // Use svelte-sonner for regular toasts
+  // Use sonner-svelte for regular toasts
   if (type !== 'undoable') {
     switch (type) {
       case 'success': sonner.success(message, { duration }); break;