@svadmin/core 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "author": "zuohuadong",
   "repository": {
     "type": "git",
@@ -10,9 +10,9 @@
   "main": "src/index.ts",
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.0",
-    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@sveltejs/vite-plugin-svelte": "^7.2.0",
     "@testing-library/dom": "^10.4.1",
-    "@testing-library/svelte": "^5.3.1",
+    "@testing-library/svelte": "^5.4.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/bun": "^1.3.14",
     "@types/jsdom": "^28.0.3",

package/src/auth-hooks.svelte.ts

@@ -2,10 +2,10 @@
 // Each hook encapsulates the auth call + loading state + error handling + redirect
 // Uses module-level $state — no component init-time constraints.
 
-import { getAuthProvider } from './context.svelte';
-import { navigate } from './router';
+import { captureAdminContext } from './context.svelte';
+import type { AdminContextAccessor } from './context.svelte';
 import { notify } from './notification.svelte';
-import { t } from './i18n.svelte';
+import { t, useTranslation } from './i18n.svelte';
 import type { AuthActionResult, CheckResult, Identity, AuthProvider } from './types';
 import { useQueryClient } from '@tanstack/svelte-query';
 
@@ -19,14 +19,16 @@ interface CreateAuthMutationOptions {
   method: keyof AuthProvider;
   successMessage?: string | null;
   errorMessage?: string | false;
-  onSuccess?: (result: AuthActionResult) => void;
+  onSuccess?: (result: AuthActionResult, adminContext: AdminContextAccessor) => void | Promise<void>;
 }
 
 function createAuthMutation(options: CreateAuthMutationOptions) {
-  const provider = getAuthProvider();
+  const adminContext = captureAdminContext();
+  const i18n = useTranslation();
   let isLoading = $state(false);
 
   async function mutate(params?: Record<string, unknown>): Promise<AuthActionResult> {
+    const provider = adminContext.authProvider;
     if (!provider) throw new Error('AuthProvider not configured');
     const fn = provider[options.method] as ((params?: Record<string, unknown>) => Promise<AuthActionResult>) | undefined;
     if (!fn) throw new Error(`AuthProvider.${options.method} not implemented`);
@@ -36,14 +38,14 @@ function createAuthMutation(options: CreateAuthMutationOptions) {
       const result = await fn.call(provider, params);
       if (result.success) {
         if (options.successMessage) notify({ type: 'success', message: options.successMessage });
-        if (options.onSuccess) options.onSuccess(result);
+        if (options.onSuccess) await options.onSuccess(result, adminContext);
       } else {
-        const msg = result.error?.message ?? (typeof options.errorMessage === 'string' ? options.errorMessage : t('common.operationFailed'));
+        const msg = result.error?.message ?? (typeof options.errorMessage === 'string' ? options.errorMessage : i18n.t('common.operationFailed'));
         if (options.errorMessage !== false) notify({ type: 'error', message: msg });
       }
       return result;
     } catch (err) {
-      const msg = err instanceof Error ? err.message : (typeof options.errorMessage === 'string' ? options.errorMessage : t('common.operationFailed'));
+      const msg = err instanceof Error ? err.message : (typeof options.errorMessage === 'string' ? options.errorMessage : i18n.t('common.operationFailed'));
       if (options.errorMessage !== false) notify({ type: 'error', message: msg });
       return { success: false, error: { message: msg } };
     } finally {
@@ -64,23 +66,26 @@ export function useLogin(opts?: { errorMessage?: string | false }) {
     method: 'login',
     successMessage: t('common.operationSuccess'),
     errorMessage: opts?.errorMessage ?? t('common.loginFailed'),
-    onSuccess: (result) => { navigate(result.redirectTo ?? '/'); }
+    onSuccess: async (result, adminContext) => { await adminContext.navigate(result.redirectTo ?? '/'); }
   });
 }
 
 // ─── useLogout ────────────────────────────────────────────────
 
 export function useLogout() {
+  let queryClient: ReturnType<typeof useQueryClient> | undefined;
+  try {
+    queryClient = useQueryClient();
+  } catch {
+    // Auth hooks remain usable without TanStack Query; cache clearing is best-effort.
+  }
   return createAuthMutation({
     method: 'logout',
     successMessage: null,
-    onSuccess: (result) => {
+    onSuccess: async (result, adminContext) => {
       _logoutVersion++;
-      try {
-        const queryClient = useQueryClient();
-        queryClient.clear();
-      } catch { /* intentional */}
-      navigate(result.redirectTo ?? '/login');
+      queryClient?.clear();
+      await adminContext.navigate(result.redirectTo ?? '/login');
     }
   });
 }
@@ -91,7 +96,9 @@ export function useRegister() {
   return createAuthMutation({
     method: 'register',
     successMessage: t('auth.registerSuccess'),
-    onSuccess: (result) => { if (result.redirectTo) navigate(result.redirectTo); }
+    onSuccess: async (result, adminContext) => {
+      if (result.redirectTo) await adminContext.navigate(result.redirectTo);
+    }
   });
 }
 
@@ -110,7 +117,9 @@ export function useUpdatePassword() {
   return createAuthMutation({
     method: 'updatePassword',
     successMessage: t('common.operationSuccess'),
-    onSuccess: (result) => { if (result.redirectTo) navigate(result.redirectTo); }
+    onSuccess: async (result, adminContext) => {
+      if (result.redirectTo) await adminContext.navigate(result.redirectTo);
+    }
   });
 }
 
@@ -120,7 +129,9 @@ export function useUpdateIdentity() {
   return createAuthMutation({
     method: 'updateIdentity',
     successMessage: t('common.operationSuccess'),
-    onSuccess: (result) => { if (result.redirectTo) navigate(result.redirectTo); }
+    onSuccess: async (result, adminContext) => {
+      if (result.redirectTo) await adminContext.navigate(result.redirectTo);
+    }
   });
 }
 
@@ -128,19 +139,22 @@ export function useUpdateProfile() {
   return createAuthMutation({
     method: 'updateProfile',
     successMessage: t('common.operationSuccess'),
-    onSuccess: (result) => { if (result.redirectTo) navigate(result.redirectTo); }
+    onSuccess: async (result, adminContext) => {
+      if (result.redirectTo) await adminContext.navigate(result.redirectTo);
+    }
   });
 }
 
 // ─── useGetIdentity ──────────────────────────────────────────
 
 export function useGetIdentity() {
-  const provider = getAuthProvider({ optional: true });
+  const adminContext = captureAdminContext();
   let data = $state<Identity | null>(null);
   let isLoading = $state(true);
   let error = $state<Error | null>(null);
 
   function fetch() {
+    const provider = adminContext.authProvider;
     if (!provider) { isLoading = false; return; }
     isLoading = true;
     provider.getIdentity().then(identity => {
@@ -172,12 +186,13 @@ export function useGetIdentity() {
 // ─── useIsAuthenticated ──────────────────────────────────────
 
 export function useIsAuthenticated() {
-  const provider = getAuthProvider({ optional: true });
+  const adminContext = captureAdminContext();
   let isAuthenticated = $state(false);
   let isLoading = $state(true);
   let checkResult = $state<CheckResult | null>(null);
 
   function check() {
+    const provider = adminContext.authProvider;
     if (!provider) {
       isAuthenticated = true;
       isLoading = false;
@@ -227,9 +242,10 @@ export function useIsAuthenticated() {
  * If it returns { redirectTo }, navigates there.
  */
 export function useOnError() {
-  const provider = getAuthProvider({ optional: true });
+  const adminContext = captureAdminContext();
 
   async function mutate(error: unknown) {
+    const provider = adminContext.authProvider;
     if (!provider?.onError) {
       console.warn('[svadmin] useOnError: authProvider.onError not implemented');
       return;
@@ -238,9 +254,9 @@ export function useOnError() {
       const result = await provider.onError(error);
       if (result.logout) {
         await provider.logout?.();
-        navigate(result.redirectTo ?? '/login');
+        await adminContext.navigate(result.redirectTo ?? '/login');
       } else if (result.redirectTo) {
-        navigate(result.redirectTo);
+        await adminContext.navigate(result.redirectTo);
       }
     } catch (err) {
       console.warn('[svadmin] useOnError failed:', err);
@@ -268,13 +284,14 @@ export function useOnError() {
  * ```
  */
 export function usePermissions<T = unknown>() {
-  const provider = getAuthProvider();
+  const adminContext = captureAdminContext();
   let permissions = $state<T | null>(null);
   let isLoading = $state(true);
   let error = $state<Error | null>(null);
   let version = $state(0);
 
   function fetch() {
+    const provider = adminContext.authProvider;
     if (!provider?.getPermissions) { isLoading = false; return; }
     isLoading = true;
     error = null;

package/src/context.svelte.ts

@@ -1,8 +1,10 @@
-// Svelte 5 Context — module-level $state singletons (no setContext/getContext required)
-// This removes the constraint that hooks must be called at component init time.
+// Svelte 5 Context — application trees use scoped context while the module-level
+// setters remain as a compatibility facade for non-component consumers.
 
+import { createContext } from 'svelte';
 import type { DataProvider, AuthProvider, ResourceDefinition, TaskProvider } from './types';
 import type { RouterProvider } from './router-provider';
+import type { LiveProvider } from './live.svelte';
 import { resetNotificationProvider } from './notification.svelte';
 import { resetAuditLogProvider } from './audit';
 import { resetAccessControlProvider } from './permissions.svelte';
@@ -11,7 +13,15 @@ import { resetI18n } from './i18n.svelte';
 import { resetChatProvider } from './chatProvider.svelte';
 import { resetToast } from './toast.svelte';
 import { resetTheme } from './theme.svelte';
-import { resetRouter } from './router';
+import {
+  currentPath as currentLegacyPath,
+  currentPathWithProvider,
+  formatLink as formatLegacyLink,
+  formatLinkWithProvider,
+  navigate as navigateLegacy,
+  navigateWithProvider,
+  resetRouter,
+} from './router';
 import { resetUnsavedChanges } from './unsaved-changes.svelte';
 import { resetGlobalPath } from './useParsed.svelte';
 import { resetLogoutVersion } from './auth-hooks.svelte';
@@ -26,46 +36,176 @@ import { resetSidebarCollapsed } from './hooks.svelte';
  */
 export type DataProviderInput = DataProvider | Record<string, DataProvider>;
 
+export interface AdminContextSource {
+  readonly dataProvider: DataProviderInput;
+  readonly authProvider?: AuthProvider | null;
+  readonly resources: ResourceDefinition[];
+  readonly routerProvider?: RouterProvider;
+  readonly liveProvider?: LiveProvider;
+  readonly taskProvider?: TaskProvider;
+}
+
+export interface AdminContextValue {
+  readonly providers: Record<string, DataProvider>;
+  readonly authProvider: AuthProvider | null;
+  readonly resources: ResourceDefinition[];
+  readonly routerProvider: RouterProvider | undefined;
+  readonly liveProvider: LiveProvider | undefined;
+  readonly taskProvider: TaskProvider | undefined;
+}
+
+/**
+ * Initialization-time snapshot of the owning AdminContext tree.
+ *
+ * The accessor keeps the scoped context object (whose fields are reactive
+ * getters) instead of calling Svelte's getContext from later DOM/query
+ * callbacks. When no scoped context exists, getters intentionally continue to
+ * read the module-level compatibility setters dynamically.
+ */
+export interface AdminContextAccessor {
+  readonly providers: Record<string, DataProvider> | null;
+  readonly authProvider: AuthProvider | null;
+  readonly resources: ResourceDefinition[];
+  readonly routerProvider: RouterProvider | undefined;
+  readonly liveProvider: LiveProvider | undefined;
+  readonly taskProvider: TaskProvider | undefined;
+  getDataProvider(name?: string): DataProvider;
+  getDataProviderNames(): string[];
+  getDataProviderForResource(resourceName: string, overrideName?: string): DataProvider;
+  getResource(nameOrIdentifier: string): ResourceDefinition;
+  currentPath(): string;
+  formatLink(path: string): string;
+  navigate(path: string, options?: { replaceState?: boolean }): Promise<void>;
+  back(): void;
+}
+
+const [getRequiredAdminContext, setAdminContext] = createContext<AdminContextValue>();
+
+function normalizeDataProviders(provider: DataProviderInput): Record<string, DataProvider> {
+  return isDataProvider(provider)
+    ? { default: provider }
+    : provider;
+}
+
+export function createAdminContext(source: AdminContextSource): AdminContextValue {
+  return {
+    get providers() { return normalizeDataProviders(source.dataProvider); },
+    get authProvider() { return source.authProvider ?? null; },
+    get resources() { return source.resources; },
+    get routerProvider() { return source.routerProvider; },
+    get liveProvider() { return source.liveProvider; },
+    get taskProvider() { return source.taskProvider; },
+  };
+}
+
+/** Provide request/tree-scoped admin state to all descendants. */
+export function provideAdminContext(source: AdminContextSource): AdminContextValue {
+  const context = createAdminContext(source);
+  setAdminContext(context);
+  return context;
+}
+
+/** Return the current tree context when called during component initialization/render. */
+export function getAdminContext(): AdminContextValue | undefined {
+  try {
+    return getRequiredAdminContext();
+  } catch {
+    return undefined;
+  }
+}
+
 let providers = $state<Record<string, DataProvider> | null>(null);
 
+/** Capture the current tree once so delayed callbacks never re-enter getContext. */
+export function captureAdminContext(): AdminContextAccessor {
+  const scopedContext = getAdminContext();
+
+  const accessor: AdminContextAccessor = {
+    get providers() { return scopedContext ? scopedContext.providers : providers; },
+    get authProvider() { return scopedContext ? scopedContext.authProvider : authProvider; },
+    get resources() { return scopedContext ? scopedContext.resources : resources ?? []; },
+    get routerProvider() { return scopedContext ? scopedContext.routerProvider : routerProvider; },
+    get liveProvider() { return scopedContext ? scopedContext.liveProvider : liveProviderState; },
+    get taskProvider() { return scopedContext ? scopedContext.taskProvider : taskProviderState; },
+    getDataProvider(name) {
+      const activeProviders = accessor.providers;
+      if (!activeProviders) throw new Error('DataProvider not found. Did you call setDataProvider in App.svelte?');
+      const key = name ?? 'default';
+      const provider = activeProviders[key];
+      if (!provider) {
+        throw new Error(`DataProvider "${key}" not found. Available: ${Object.keys(activeProviders).join(', ')}`);
+      }
+      return provider;
+    },
+    getDataProviderNames() {
+      return accessor.providers ? Object.keys(accessor.providers) : [];
+    },
+    getDataProviderForResource(resourceName, overrideName) {
+      if (overrideName) {
+        try {
+          return accessor.getDataProvider(overrideName);
+        } catch {
+          // Preserve the historical fallback to the resource/default provider.
+        }
+      }
+      try {
+        const resource = accessor.getResource(resourceName);
+        const dataProviderName = resource.meta?.dataProviderName as string | undefined;
+        if (dataProviderName) return accessor.getDataProvider(dataProviderName);
+      } catch {
+        // Preserve the historical fallback when a resource is not registered.
+      }
+      return accessor.getDataProvider();
+    },
+    getResource(nameOrIdentifier) {
+      const resource = accessor.resources.find(
+        (candidate) => candidate.identifier === nameOrIdentifier || candidate.name === nameOrIdentifier,
+      );
+      if (!resource) throw new Error(`Resource "${nameOrIdentifier}" not found in resource definitions.`);
+      return resource;
+    },
+    currentPath() {
+      if (scopedContext) return currentPathWithProvider(scopedContext.routerProvider);
+      return currentLegacyPath();
+    },
+    formatLink(path) {
+      if (scopedContext) return formatLinkWithProvider(scopedContext.routerProvider, path);
+      return formatLegacyLink(path);
+    },
+    async navigate(path, options) {
+      if (scopedContext) {
+        await navigateWithProvider(scopedContext.routerProvider, path, options);
+        return;
+      }
+      await navigateLegacy(path, options);
+    },
+    back() {
+      const activeRouter = accessor.routerProvider;
+      if (activeRouter?.back) {
+        activeRouter.back();
+      } else if (typeof window !== 'undefined') {
+        window.history.back();
+      }
+    },
+  };
+
+  return accessor;
+}
+
 export function setDataProvider(provider: DataProviderInput): void {
-  if (isDataProvider(provider)) {
-    providers = { default: provider } as Record<string, DataProvider>;
-  } else {
-    providers = provider as Record<string, DataProvider>;
-  }
+  providers = normalizeDataProviders(provider);
 }
 
 export function getDataProvider(name?: string): DataProvider {
-  if (!providers) throw new Error('DataProvider not found. Did you call setDataProvider in App.svelte?');
-  const key = name ?? 'default';
-  const provider = providers[key];
-  if (!provider) {
-    throw new Error(`DataProvider "${key}" not found. Available: ${Object.keys(providers).join(', ')}`);
-  }
-  return provider;
+  return captureAdminContext().getDataProvider(name);
 }
 
 export function getDataProviderNames(): string[] {
-  return providers ? Object.keys(providers) : [];
+  return captureAdminContext().getDataProviderNames();
 }
 
 export function getDataProviderForResource(resourceName: string, overrideName?: string): DataProvider {
-  if (overrideName) {
-    try {
-      return getDataProvider(overrideName);
-    } catch {
-      // ignore
-    }
-  }
-  try {
-    const resource = getResource(resourceName);
-    const dpName = resource.meta?.dataProviderName as string | undefined;
-    if (dpName) return getDataProvider(dpName);
-  } catch {
-    // ignore
-  }
-  return getDataProvider();
+  return captureAdminContext().getDataProviderForResource(resourceName, overrideName);
 }
 
 function isDataProvider(value: unknown): value is DataProvider {
@@ -88,8 +228,9 @@ export function setAuthProvider(provider: AuthProvider | null | undefined): void
 export function getAuthProvider(): AuthProvider;
 export function getAuthProvider(options: { optional: true }): AuthProvider | null;
 export function getAuthProvider(options?: { optional?: boolean }): AuthProvider | null {
-  if (!authProvider && !options?.optional) throw new Error('AuthProvider not found. Did you call setAuthProvider in App.svelte?');
-  return authProvider;
+  const activeAuthProvider = captureAdminContext().authProvider;
+  if (!activeAuthProvider && !options?.optional) throw new Error('AuthProvider not found. Did you call setAuthProvider in App.svelte?');
+  return activeAuthProvider;
 }
 
 // ─── Resources ──────────────────────────────────────────────────
@@ -101,39 +242,36 @@ export function setResources(newResources: ResourceDefinition[]): void {
 }
 
 export function getResources(): ResourceDefinition[] {
-  return resources ?? [];
+  return captureAdminContext().resources;
 }
 
 export function getResource(nameOrIdentifier: string): ResourceDefinition {
-  const rList = getResources();
-  const resource = rList.find(r => r.identifier === nameOrIdentifier || r.name === nameOrIdentifier);
-  if (!resource) throw new Error(`Resource "${nameOrIdentifier}" not found in resource definitions.`);
-  return resource;
+  return captureAdminContext().getResource(nameOrIdentifier);
 }
 
 // ─── Router Provider ────────────────────────────────────────────
 
 let routerProvider = $state<RouterProvider | undefined>(undefined);
 
-export function setRouterProvider(provider: RouterProvider): void {
+export function setRouterProvider(provider: RouterProvider | undefined): void {
   routerProvider = provider;
 }
 
 export function getRouterProvider(): RouterProvider | undefined {
-  return routerProvider;
+  return captureAdminContext().routerProvider;
 }
 
 
 // ─── Live Provider ──────────────────────────────────────────────
 
-let liveProviderState = $state<import('./live.svelte').LiveProvider | undefined>(undefined);
+let liveProviderState = $state<LiveProvider | undefined>(undefined);
 
-export function setLiveProvider(provider: import('./live.svelte').LiveProvider): void {
+export function setLiveProvider(provider: LiveProvider): void {
   liveProviderState = provider;
 }
 
-export function getLiveProvider(): import('./live.svelte').LiveProvider | undefined {
-  return liveProviderState;
+export function getLiveProvider(): LiveProvider | undefined {
+  return captureAdminContext().liveProvider;
 }
 
 // ─── Task Provider ──────────────────────────────────────────────
@@ -147,10 +285,11 @@ export function setTaskProvider(provider: TaskProvider | undefined): void {
 export function getTaskProvider(): TaskProvider;
 export function getTaskProvider(options: { optional: true }): TaskProvider | undefined;
 export function getTaskProvider(options?: { optional?: boolean }): TaskProvider | undefined {
-  if (!taskProviderState && !options?.optional) {
+  const activeTaskProvider = captureAdminContext().taskProvider;
+  if (!activeTaskProvider && !options?.optional) {
     throw new Error('TaskProvider not found. Did you call setTaskProvider in App.svelte?');
   }
-  return taskProviderState;
+  return activeTaskProvider;
 }
 
 // ─── Reset — for testing / HMR ─────────────────────────────────

package/src/data-transfer.svelte.ts

@@ -1,4 +1,4 @@
-import { getDataProviderForResource } from './context.svelte';
+import { captureAdminContext } from './context.svelte';
 import { useParsed } from './useParsed.svelte';
 import type { Sort, Filter, BaseRecord } from './types';
 import { downloadData } from './export-format';
@@ -26,6 +26,7 @@ export interface UseExportOptions<TData extends BaseRecord = BaseRecord> {
  * Supports mapData, sorters, filters, maxItemCount, pageSize
  */
 export function useExport<TData extends BaseRecord = BaseRecord>(options: UseExportOptions<TData> = {}) {
+  const adminContext = captureAdminContext();
   const parsed = useParsed();
   const resource = $derived(options.resource ?? parsed.resource ?? '');
   let isLoading = $state(false);
@@ -35,7 +36,7 @@ export function useExport<TData extends BaseRecord = BaseRecord>(options: UseExp
     isLoading = true;
 
     try {
-      const provider = getDataProviderForResource(exportResource, options.dataProviderName);
+      const provider = adminContext.getDataProviderForResource(exportResource, options.dataProviderName);
       const batchSize = options.pageSize ?? 20;
       const maxItems = options.maxItemCount ?? Infinity;
       let allRecords: TData[] = [];
@@ -98,6 +99,7 @@ export interface UseImportOptions<TData = Record<string, unknown>> {
  * Supports mapData, batchSize, onFinish, onProgress, meta
  */
 export function useImport<TData = Record<string, unknown>>(options: UseImportOptions<TData> = {}) {
+  const adminContext = captureAdminContext();
   const parsed = useParsed();
   const resource = $derived(options.resource ?? parsed.resource ?? '');
   let isLoading = $state(false);
@@ -110,7 +112,7 @@ export function useImport<TData = Record<string, unknown>>(options: UseImportOpt
     const errored: { request: unknown; error: unknown }[] = [];
 
     try {
-      const provider = getDataProviderForResource(importResource, options.dataProviderName);
+      const provider = adminContext.getDataProviderForResource(importResource, options.dataProviderName);
       let text = await info.file.text();
       // Strip BOM
       if (text.charCodeAt(0) === 0xFEFF) {