@svadmin/core 0.18.1 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.18.1",
+  "version": "0.19.1",
   "author": "zuohuadong",
   "repository": {
     "type": "git",

package/src/auth-hooks.svelte.ts

@@ -266,7 +266,9 @@ export function useOnError() {
 
 /**
  * Fetches permissions from authProvider.getPermissions().
- * Returns a reactive integrated object.
+ * Returns a reactive object with convenience methods for permission checks.
+ * 
+ * Supports `refetch()` for session-level permission refresh (e.g., after role change).
  * 
  * @example
  * ```svelte
@@ -282,9 +284,12 @@ export function usePermissions<T = unknown>() {
   let permissions = $state<T | null>(null);
   let isLoading = $state(true);
   let error = $state<Error | null>(null);
-  let version = $state(0); // Force reactive invalidation
+  let version = $state(0);
 
-  if (provider?.getPermissions) {
+  function fetch() {
+    if (!provider?.getPermissions) { isLoading = false; return; }
+    isLoading = true;
+    error = null;
     provider.getPermissions().then(p => {
       permissions = p as T;
       version++;
@@ -294,19 +299,18 @@ export function usePermissions<T = unknown>() {
       isLoading = false;
       console.warn('[svadmin] usePermissions failed:', err);
     });
-  } else {
-    isLoading = false;
   }
 
+  fetch();
+
   return {
     get isLoading() { return isLoading; },
     get error() { return error; },
     get version() { return version; },
-    
-    /** Get the raw permissions data */
     get raw() { return permissions; },
+    refetch: fetch,
 
-    /** Convenience: check if a specific permission exists */
+    /** Check if a specific permission string exists */
     has(perm: string): boolean {
       if (!permissions) return false;
       if (Array.isArray(permissions)) return permissions.includes(perm);
@@ -315,12 +319,10 @@ export function usePermissions<T = unknown>() {
       return false;
     },
 
-    /** Convenience: check resource action (Casbin style representation if applicable) */
+    /** Check resource:action style permission */
     can(resource: string, action: string): boolean {
-      // Tries to map to a standard permission string format like "resource:action" 
-      // Replace with your own logic if your permissions are structured differently.
       return this.has(`${resource}:${action}`);
-    }
+    },
   };
 }
 

package/src/form-hooks.svelte.ts

@@ -326,10 +326,16 @@ export function useForm<
 
     if (!runValidation()) { toast.warning(t('validation.required')); return; }
     redirectOverride = overrides?.redirect;
-    if (action === 'create' || action === 'clone') await createMut.mutateAsync(values);
-    else await updateMut.mutateAsync(values);
-    // Untaint on success
-    tainted = {};
+    try {
+      if (action === 'create' || action === 'clone') await createMut.mutateAsync(values);
+      else await updateMut.mutateAsync(values);
+      // Untaint on success
+      tainted = {};
+    } catch (error) {
+      // Errors are already handled by the mutation's onError callback.
+      // We catch here to prevent unhandled promise rejections.
+      handleHttpError(error instanceof Error ? error : new Error(String(error)));
+    }
   }
 
   // ─── AutoSave ───────────────────────────────────────────────────

package/src/hooks.svelte.ts

@@ -170,6 +170,11 @@ export function useSelect<TData extends BaseRecord = BaseRecord, TOption = { lab
     debounceTimer = setTimeout(() => { searchText = value; }, debounceMs);
   }
 
+  // Cleanup debounce timer on unmount
+  $effect(() => {
+    return () => { if (debounceTimer) clearTimeout(debounceTimer); };
+  });
+
   return {
     query,
     get options() { return selectOptions; },

package/src/i18n.svelte.ts

@@ -519,13 +519,23 @@ export function addTranslations(locale: string, translations: Record<string, str
 }
 
 /**
- * useTranslation — standard i18n hook
- * Returns { translate, getLocale, changeLocale }
+ * useTranslation — Svelte 5 reactive translation hook
+ * Tracks locale changes natively.
  */
 export function useTranslation() {
-  return {
-    translate: t,
-    getLocale,
-    changeLocale: setLocale,
+  const translate = $derived.by(() => {
+    // Read currentLocale so this $derived depends on it
+    const loc = currentLocale;
+    return (key: string, params?: Record<string, string | number>): string => {
+      // Intentionally passing the key to the main t() function which uses currentLocale
+      return t(key, params);
+    };
+  });
+  
+  return { 
+    get t() { return translate; },
+    get locale() { return currentLocale; },
+    setLocale,
+    getAvailableLocales
   };
 }

package/src/permissions.test.ts

@@ -1,6 +1,6 @@
 // Unit tests for permissions module
 import { describe, test, expect, beforeEach } from 'bun:test';
-import { setAccessControlProvider, getAccessControlProvider, getAccessControlOptions, canAccessAsync } from './permissions';
+import { setAccessControlProvider, getAccessControlProvider, getAccessControlOptions, canAccessAsync, type CanParams, type CanResult } from './permissions';
 import type { Action, AccessControlProvider } from './permissions';
 
 describe('permissions', () => {
@@ -13,21 +13,26 @@ describe('permissions', () => {
 
   test('canAccessAsync respects deny rule', async () => {
     setAccessControlProvider({
-      can: async ({ action }) => {
+      can: async (p) => {
+        const { action } = p as CanParams;
         if (action === 'delete') return { can: false, reason: 'Denied' };
         return { can: true };
       },
     });
     expect(await canAccessAsync('posts', 'delete')).toEqual({ can: false, reason: 'Denied' });
-    expect(await canAccessAsync('posts', 'list')).toEqual({ can: true });
+    expect((await canAccessAsync('posts', 'delete')) as CanResult).toEqual({ can: false, reason: 'Denied' });
+    expect((await canAccessAsync('posts', 'list')) as CanResult).toEqual({ can: true });
   });
 
   test('canAccessAsync resolves with allowed status', async () => {
     setAccessControlProvider({
-      can: async () => ({ can: true }),
+      can: async (params) => {
+        expect((params as CanParams).params?.published).toBe(true);
+        return { can: true };
+      },
     });
-    const result = await canAccessAsync('posts', 'edit');
-    expect((result as any).can).toBe(true);
+    const result = await canAccessAsync('posts', 'edit', { published: true });
+    expect((result as CanResult).can).toBe(true);
   });
 
   test('canAccessAsync resolves with denied status', async () => {
@@ -35,20 +40,21 @@ describe('permissions', () => {
       can: async () => ({ can: false, reason: 'No permission' }),
     });
     const result = await canAccessAsync('users', 'delete');
-    expect((result as any).can).toBe(false);
-    expect((result as any).reason).toBe('No permission');
+    expect((result as CanResult).can).toBe(false);
+    expect((result as CanResult).reason).toBe('No permission');
   });
 
   test('resource-specific rules', async () => {
     setAccessControlProvider({
-      can: async ({ resource, action }) => {
+      can: async (p) => {
+        const { resource, action } = p as CanParams;
         if (resource === 'users' && action === 'delete') return { can: false, reason: 'Cannot delete users' };
         return { can: true };
       },
     });
-    expect((await canAccessAsync('users', 'delete')).can).toBe(false);
-    expect((await canAccessAsync('users', 'list')).can).toBe(true);
-    expect((await canAccessAsync('posts', 'delete')).can).toBe(true);
+    expect((await canAccessAsync('users', 'delete') as CanResult).can).toBe(false);
+    expect((await canAccessAsync('users', 'list') as CanResult).can).toBe(true);
+    expect((await canAccessAsync('posts', 'delete') as CanResult).can).toBe(true);
   });
 });
 
@@ -65,45 +71,51 @@ describe('AccessControlProvider', () => {
   });
 
   test('provider can() is called via canAccessAsync', async () => {
+    let callCount = 0;
     setAccessControlProvider({
-      can: async ({ resource, action }) => {
-        if (resource === 'posts' && action === 'delete') {
+      can: async (params) => {
+        callCount++;
+        expect((params as CanParams).resource).toBe('posts');
+        if ((params as CanParams).action === 'delete') {
           return { can: false, reason: 'Cannot delete posts' };
         }
         return { can: true };
       },
     });
-    const denied = await canAccessAsync('posts', 'delete');
+    const denied = await canAccessAsync('posts', 'delete') as CanResult;
     expect(denied.can).toBe(false);
     expect(denied.reason).toBe('Cannot delete posts');
 
-    const allowed = await canAccessAsync('posts', 'list');
+    const allowed = await canAccessAsync('posts', 'list') as CanResult;
     expect(allowed.can).toBe(true);
+    expect(callCount).toBe(2);
   });
 
   test('params.id is passed through', async () => {
     setAccessControlProvider({
-      can: async ({ params }) => {
+      can: async (p) => {
+        const { params } = p as CanParams;
         if (params?.id === 42) return { can: false, reason: 'Record locked' };
         return { can: true };
       },
     });
     const result = await canAccessAsync('posts', 'edit', { id: 42 });
-    expect((result as any).can).toBe(false);
-    expect((result as any).reason).toBe('Record locked');
+    expect((result as CanResult).can).toBe(false);
+    expect((result as CanResult).reason).toBe('Record locked');
   });
 
   test('extended action types work', async () => {
     setAccessControlProvider({
-      can: async ({ action }) => {
+      can: async (p) => {
+        const { action } = p as CanParams;
         if (action === 'show') return { can: false, reason: 'No show' };
         if (action === 'field') return { can: false, reason: 'No field' };
         return { can: true };
       },
     });
-    expect((await canAccessAsync('posts', 'show')).can).toBe(false);
-    expect((await canAccessAsync('posts', 'field')).can).toBe(false);
-    expect((await canAccessAsync('posts', 'list')).can).toBe(true);
+    expect(((await canAccessAsync('posts', 'show')) as CanResult).can).toBe(false);
+    expect(((await canAccessAsync('posts', 'field')) as CanResult).can).toBe(false);
+    expect(((await canAccessAsync('posts', 'list')) as CanResult).can).toBe(true);
   });
 
   test('getAccessControlOptions returns provider options', () => {
@@ -139,10 +151,10 @@ describe('CASL adapter', () => {
 
     const provider = createCaslAccessControl(ability);
 
-    const allowed = await provider.can({ resource: 'posts', action: 'edit' });
+    const allowed = await provider.can({ resource: 'posts', action: 'edit' }) as CanResult;
     expect(allowed.can).toBe(true);
 
-    const denied = await provider.can({ resource: 'users', action: 'delete' });
+    const denied = await provider.can({ resource: 'users', action: 'delete' }) as CanResult;
     expect(denied.can).toBe(false);
     expect(denied.reason).toContain('Cannot "delete" on "users"');
   });
@@ -162,10 +174,10 @@ describe('Casbin adapter', () => {
       getUser: () => 'alice',
     });
 
-    const allowed = await provider.can({ resource: 'posts', action: 'edit' });
+    const allowed = await provider.can({ resource: 'posts', action: 'edit' }) as CanResult;
     expect(allowed.can).toBe(true);
 
-    const denied = await provider.can({ resource: 'users', action: 'delete' });
+    const denied = await provider.can({ resource: 'users', action: 'delete' }) as CanResult;
     expect(denied.can).toBe(false);
     expect(denied.reason).toContain('alice');
   });

package/src/theme.svelte.ts

@@ -336,7 +336,7 @@ function applyTheme(m: ThemeMode): void {
 }
 
 // Apply on init
-applyTheme(mode);
+applyTheme(getStoredTheme());
 
 // Listen for system preference changes
 if (typeof window !== 'undefined') {
@@ -383,7 +383,7 @@ function applyColorTheme(ct: ColorTheme): void {
 }
 
 // Apply on init
-applyColorTheme(colorTheme);
+applyColorTheme(getStoredColorTheme());
 
 export function getColorTheme(): ColorTheme {
   return colorTheme;

package/src/unsaved-changes.svelte.ts

@@ -1,62 +1,114 @@
-// UnsavedChangesNotifier — warns user before leaving page with unsaved changes
-// Svelte 5 component using runes
+// UnsavedChangesNotifier — guards against accidental navigation with dirty forms
+// Supports: browser tab close, hash-based SPA routing, and framework router interception
 
-// No lifecycle imports needed — uses module-level $state pattern
+import { t } from './i18n.svelte';
 
-let warnWhenUnsavedChanges = $state(false);
+let dirty = $state(false);
 
-/**
- * Call this to mark the form as dirty (has unsaved changes).
- * When set to true, navigating away or closing the tab will trigger a warning.
- */
-export function setUnsavedChanges(dirty: boolean) {
-  warnWhenUnsavedChanges = dirty;
+/** Mark whether the current form has unsaved changes */
+export function setUnsavedChanges(value: boolean) {
+  dirty = value;
 }
 
 export function getUnsavedChanges(): boolean {
-  return warnWhenUnsavedChanges;
+  return dirty;
 }
 
-const beforeUnloadHandler = (e: BeforeUnloadEvent) => {
-  if (warnWhenUnsavedChanges) {
-    e.preventDefault();
-    // Modern browsers ignore custom messages but require returnValue to be set
-    e.returnValue = '';
-    return '';
-  }
-};
+/**
+ * Navigation interceptor callback type.
+ * Frameworks like SvelteKit can register a cancel function here.
+ * Return `true` to allow navigation, `false` to block it.
+ */
+type NavigationGuard = (opts: { cancel: () => void }) => void;
+
+let _navigationGuard: NavigationGuard | null = null;
+
+/**
+ * Register a framework-level navigation guard.
+ * 
+ * In SvelteKit, call this from your root layout:
+ * ```ts
+ * import { beforeNavigate } from '$app/navigation';
+ * import { registerNavigationGuard } from '@svadmin/core';
+ * 
+ * registerNavigationGuard(({ cancel }) => {
+ *   beforeNavigate(({ cancel: kitCancel }) => {
+ *     cancel = kitCancel;
+ *   });
+ * });
+ * ```
+ * 
+ * Or more idiomatically, use the built-in `initUnsavedChangesNotifier` 
+ * and pass a `beforeNavigate` callback.
+ */
+export function registerNavigationGuard(guard: NavigationGuard): void {
+  _navigationGuard = guard;
+}
 
 /**
  * Initialize the UnsavedChangesNotifier.
- * Call this in your root layout or AdminApp component.
- * It handles both browser tab close and in-app navigation.
+ * 
+ * @param options.beforeNavigate - Framework-level navigation interceptor.
+ *   For SvelteKit: pass the `beforeNavigate` function from `$app/navigation`.
+ *   For hash-based SPAs: omit this, hash navigation is handled automatically.
+ * 
+ * @example SvelteKit
+ * ```svelte
+ * <script>
+ *   import { beforeNavigate } from '$app/navigation';
+ *   import { initUnsavedChangesNotifier } from '@svadmin/core';
+ *   initUnsavedChangesNotifier({ beforeNavigate });
+ * </script>
+ * ```
+ * 
+ * @example Hash-based SPA
+ * ```ts
+ * initUnsavedChangesNotifier();
+ * ```
  */
-export function initUnsavedChangesNotifier() {
+export function initUnsavedChangesNotifier(options?: {
+  beforeNavigate?: (callback: (nav: { cancel: () => void }) => void) => void;
+}) {
   if (typeof window === 'undefined') return;
 
-  window.addEventListener('beforeunload', beforeUnloadHandler);
-
-  // For hash-based navigation, intercept hashchange
-  const hashChangeHandler = (e: HashChangeEvent) => {
-    if (warnWhenUnsavedChanges) {
-      const confirmed = confirm('You have unsaved changes. Are you sure you want to leave?');
-      if (!confirmed) {
-        e.preventDefault();
-        // Restore original hash
-        if (e.oldURL) {
-          const oldHash = new URL(e.oldURL).hash;
-          history.replaceState(null, '', oldHash || '#');
+  // 1. Browser tab close / refresh
+  const onBeforeUnload = (e: BeforeUnloadEvent) => {
+    if (!dirty) return;
+    e.preventDefault();
+    e.returnValue = '';
+  };
+  window.addEventListener('beforeunload', onBeforeUnload);
+
+  // 2. Framework router (SvelteKit, etc.)
+  if (options?.beforeNavigate) {
+    options.beforeNavigate(({ cancel }) => {
+      if (dirty) {
+        if (!confirm(t('common.unsavedChanges'))) {
+          cancel();
+        } else {
+          dirty = false;
         }
-      } else {
-        warnWhenUnsavedChanges = false;
       }
+    });
+  }
+
+  // 3. Hash-based fallback for SPAs without a framework router
+  const onHashChange = (e: HashChangeEvent) => {
+    if (!dirty) return;
+    if (!confirm(t('common.unsavedChanges'))) {
+      e.preventDefault();
+      if (e.oldURL) {
+        history.replaceState(null, '', new URL(e.oldURL).hash || '#');
+      }
+    } else {
+      dirty = false;
     }
   };
+  window.addEventListener('hashchange', onHashChange);
 
-  window.addEventListener('hashchange', hashChangeHandler);
-
+  // Cleanup
   return () => {
-    window.removeEventListener('beforeunload', beforeUnloadHandler);
-    window.removeEventListener('hashchange', hashChangeHandler);
+    window.removeEventListener('beforeunload', onBeforeUnload);
+    window.removeEventListener('hashchange', onHashChange);
   };
 }