@svadmin/core 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Core SDK — hooks, types, context, i18n, permissions, router",
   "type": "module",
   "sideEffects": false,
@@ -59,5 +59,8 @@
   },
   "devDependencies": {
     "@types/bun": "^1.3.11"
+  },
+  "dependencies": {
+    "svelte-sonner": "^1.1.0"
   }
 }

package/src/auth-hooks.svelte.ts

@@ -1,9 +1,8 @@
 // Auth Hooks — reactive wrappers around AuthProvider methods
 // Each hook encapsulates the auth call + loading state + error handling + redirect
-// IMPORTANT: getAuthProvider() must be called at hook creation time (during component init),
-//            not inside mutate(), because Svelte's getContext() only works during init.
+// Uses module-level $state — no component init-time constraints.
 
-import { getAuthProvider } from './context';
+import { getAuthProvider } from './context.svelte';
 import { navigate } from './router';
 import { toast } from './toast.svelte';
 import { t } from './i18n.svelte';

package/src/{context.ts → context.svelte.ts}

@@ -1,14 +1,9 @@
-// Svelte context — provides DataProvider, AuthProvider, and Resources to all components
+// Svelte 5 Context — module-level $state singletons (no setContext/getContext required)
+// This removes the constraint that hooks must be called at component init time.
 
-import { getContext, setContext } from 'svelte';
 import type { DataProvider, AuthProvider, ResourceDefinition } from './types';
 import type { RouterProvider } from './router-provider';
 
-const DATA_PROVIDER_KEY = Symbol('data-provider');
-const AUTH_PROVIDER_KEY = Symbol('auth-provider');
-const RESOURCES_KEY = Symbol('resources');
-const ROUTER_PROVIDER_KEY = Symbol('router-provider');
-
 // ─── DataProvider (supports single or multiple) ─────────────────
 
 /**
@@ -18,16 +13,17 @@ const ROUTER_PROVIDER_KEY = Symbol('router-provider');
  */
 export type DataProviderInput = DataProvider | Record<string, DataProvider>;
 
+let providers = $state<Record<string, DataProvider> | null>(null);
+
 export function setDataProvider(provider: DataProviderInput): void {
   if (isDataProvider(provider)) {
-    setContext(DATA_PROVIDER_KEY, { default: provider } as Record<string, DataProvider>);
+    providers = { default: provider } as Record<string, DataProvider>;
   } else {
-    setContext(DATA_PROVIDER_KEY, provider as Record<string, DataProvider>);
+    providers = provider as Record<string, DataProvider>;
   }
 }
 
 export function getDataProvider(name?: string): DataProvider {
-  const providers = getContext<Record<string, DataProvider>>(DATA_PROVIDER_KEY);
   if (!providers) throw new Error('DataProvider not found. Did you call setDataProvider in App.svelte?');
   const key = name ?? 'default';
   const provider = providers[key];
@@ -38,7 +34,6 @@ export function getDataProvider(name?: string): DataProvider {
 }
 
 export function getDataProviderNames(): string[] {
-  const providers = getContext<Record<string, DataProvider>>(DATA_PROVIDER_KEY);
   return providers ? Object.keys(providers) : [];
 }
 
@@ -71,41 +66,58 @@ function isDataProvider(value: unknown): value is DataProvider {
 
 // ─── Auth Provider ──────────────────────────────────────────────
 
+let authProvider = $state<AuthProvider | null>(null);
+
 export function setAuthProvider(provider: AuthProvider): void {
-  setContext(AUTH_PROVIDER_KEY, provider);
+  authProvider = provider;
 }
 
 export function getAuthProvider(): AuthProvider {
-  const provider = getContext<AuthProvider>(AUTH_PROVIDER_KEY);
-  if (!provider) throw new Error('AuthProvider not found. Did you call setAuthProvider in App.svelte?');
-  return provider;
+  if (!authProvider) throw new Error('AuthProvider not found. Did you call setAuthProvider in App.svelte?');
+  return authProvider;
 }
 
 // ─── Resources ──────────────────────────────────────────────────
 
-export function setResources(resources: ResourceDefinition[]): void {
-  setContext(RESOURCES_KEY, resources);
+let resources = $state.raw<ResourceDefinition[]>([]);
+
+export function setResources(newResources: ResourceDefinition[]): void {
+  resources = newResources;
 }
 
 export function getResources(): ResourceDefinition[] {
-  const resources = getContext<ResourceDefinition[]>(RESOURCES_KEY);
-  if (!resources) throw new Error('Resources not found. Did you call setResources in App.svelte?');
+  if (!resources || resources.length === 0) throw new Error('Resources not found. Did you call setResources in App.svelte?');
   return resources;
 }
 
 export function getResource(nameOrIdentifier: string): ResourceDefinition {
-  const resources = getResources();
-  const resource = resources.find(r => r.identifier === nameOrIdentifier || r.name === nameOrIdentifier);
+  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;
 }
 
 // ─── Router Provider ────────────────────────────────────────────
 
+let routerProvider = $state<RouterProvider | undefined>(undefined);
+
 export function setRouterProvider(provider: RouterProvider): void {
-  setContext(ROUTER_PROVIDER_KEY, provider);
+  routerProvider = provider;
 }
 
 export function getRouterProvider(): RouterProvider | undefined {
-  return getContext<RouterProvider>(ROUTER_PROVIDER_KEY);
+  return routerProvider;
+}
+
+
+// ─── Live Provider ──────────────────────────────────────────────
+
+let liveProviderState: import('./live').LiveProvider | undefined = undefined;
+
+export function setLiveProvider(provider: import('./live').LiveProvider): void {
+  liveProviderState = provider;
+}
+
+export function getLiveProvider(): import('./live').LiveProvider | undefined {
+  return liveProviderState;
 }

package/src/data-transfer.ts

@@ -1,4 +1,4 @@
-import { getDataProviderForResource } from './context';
+import { getDataProviderForResource } from './context.svelte';
 import { useParsed } from './useParsed';
 import type { GetListResult, Sort, Filter, BaseRecord } from './types';
 

package/src/form-hooks.svelte.ts

@@ -1,7 +1,7 @@
 import { useQueryClient } from '@tanstack/svelte-query';
 import { useParsed } from './useParsed';
 import { getAdminOptions } from './options';
-import { getDataProviderForResource } from './context';
+import { getDataProviderForResource } from './context.svelte';
 import { createQuery, createMutation } from '@tanstack/svelte-query';
 import { toast } from './toast.svelte';
 import { t } from './i18n.svelte';
@@ -103,7 +103,7 @@ export function useForm<
   let errors = $state<Record<string, string>>({});
   function setFieldError(field: string, message: string) { errors = { ...errors, [field]: message }; }
   function clearErrors() { errors = {}; }
-  function clearFieldError(field: string) { const next = { ...errors }; delete next[field]; errors = next; }
+  function clearFieldError(field: string) { delete errors[field]; }
 
   function runValidation(values: TVariables): boolean {
     clearErrors();
@@ -178,14 +178,14 @@ export function useForm<
   async function onFinish(values: TVariables, finishOptions?: { redirect?: 'list' | 'edit' | 'show' | false }) {
     if (!runValidation(values)) { toast.warning(t('validation.required')); return; }
     redirectOverride = finishOptions?.redirect;
-    if (action === 'create' || action === 'clone') await (createMut as any).mutateAsync(values);
-    else await (updateMut as any).mutateAsync(values);
+    if (action === 'create' || action === 'clone') await createMut.mutateAsync(values);
+    else await updateMut.mutateAsync(values);
   }
 
   async function onFinishAutoSave(values: TVariables) {
     if (action === 'create' || action === 'clone') return; // Only autosave on edit
     redirectOverride = false; // Never redirect on autoSave
-    await (updateMut as any).mutateAsync(values);
+    await updateMut.mutateAsync(values);
   }
 
   let autoSaveStatus = $state<'idle' | 'saving' | 'saved' | 'error'>('idle');
@@ -244,7 +244,7 @@ export function useForm<
 
   return {
     query,
-    get formLoading() { return ((query as any)?.isLoading ?? false) || (createMut as any).isPending || (updateMut as any).isPending; },
+    get formLoading() { return (query?.isLoading ?? false) || createMut.isPending || updateMut.isPending; },
     mutation: action === 'edit' ? updateMut : createMut,
     onFinish,
     onFinishAutoSave,

package/src/hooks.svelte.ts

@@ -23,7 +23,7 @@ export type { OvertimeResult, OvertimeOptions, NotificationConfig } from './hook
 
 import { createQuery, createInfiniteQuery, createMutation, useQueryClient } from '@tanstack/svelte-query';
 import { getAdminOptions } from './options';
-import { getDataProviderForResource, getDataProvider } from './context';
+import { getDataProviderForResource, getDataProvider } from './context.svelte';
 import { useParsed } from './useParsed';
 import { createOvertimeTracker, fireSuccessNotification, fireErrorNotification } from './hook-utils.svelte';
 import type { NotificationConfig, OvertimeOptions } from './hook-utils.svelte';
@@ -203,7 +203,7 @@ export function useCustom<TData = unknown, TError = HttpError>(options: UseCusto
       return provider.custom<TData>({
         url: options.url,
         method: options.method,
-        payload: options.config?.payload as any,
+        payload: options.config?.payload,
         query: options.config?.query,
         headers: options.config?.headers,
         sorters: options.config?.sorters,
@@ -229,7 +229,7 @@ export function useCustomMutation<TData = unknown, TError = HttpError, TVariable
   const mutation = createMutation<{ data: TData }, TError, { url: string; method: 'get' | 'post' | 'put' | 'patch' | 'delete'; values?: TVariables; meta?: Record<string, unknown> }>(() => ({
     mutationFn: async (params) => {
       if (!provider.custom) throw new Error('DataProvider does not support custom method');
-      return provider.custom<TData>({ url: params.url, method: params.method, payload: params.values as any, meta: params.meta });
+      return provider.custom<TData>({ url: params.url, method: params.method, payload: params.values, meta: params.meta });
     },
   }));
 

package/src/i18n.svelte.ts

@@ -38,6 +38,9 @@ const locales: Record<string, Locale> = {
     'common.home': '首页',
     'common.logout': '退出登录',
     'common.toggleTheme': '切换主题',
+    'common.switchLanguage': '切换语言',
+    'common.clear': '清除',
+    'common.menu': '菜单',
     'common.darkMode': '暗色模式',
     'common.lightMode': '亮色模式',
     'common.detail': '详情',
@@ -47,19 +50,39 @@ const locales: Record<string, Locale> = {
     'common.retry': '重试',
     'common.yes': '是',
     'common.no': '否',
+    'common.undo': '撤销',
+    'common.filter': '筛选',
+    'common.reset': '重置',
     'common.welcome': '欢迎使用 {title}',
     'common.dashboardHint': '从侧边栏选择一个资源开始。',
     'common.redirecting': '正在跳转到登录页...',
+    'common.expand': '展开',
+    'common.collapse': '收起',
+    'common.close': '关闭',
+    'common.copy': '复制',
+    'common.copyAll': '复制全部',
+    'common.copied': '已复制',
+    'common.next': '下一步',
+    'common.back': '返回',
+    'common.step': '步骤',
+    'common.columns': '列',
+    'common.perPage': '每页',
+    'common.copyId': '复制 ID',
+    'common.showMore': '展开更多',
+    'common.showLess': '收起',
     // Field
     'field.enterValue': '输入{label}',
     'field.selectPlaceholder': '请选择',
     'field.tagsPlaceholder': '输入标签后按回车...',
+    'field.noOptions': '无可用选项',
+    'field.addImage': '添加图片',
     // Config errors
     'config.missingEnvTitle': '环境配置缺失',
     'config.missingEnvDescription': '应用无法启动，因为缺少必要的环境变量。',
     'config.addToEnvFile': '请在 .env 文件中添加以下内容：',
     'config.envFilePath': '文件路径: .env',
     'config.reload': '配置完成后刷新页面',
+    'config.reloadButton': '重新加载页面',
     // Auth pages
     'auth.login': '登录',
     'auth.register': '注册',
@@ -86,6 +109,17 @@ const locales: Record<string, Locale> = {
     'auth.welcomeMessage': '登录以继续使用管理后台',
     'auth.createAccount': '创建账号',
     'auth.createAccountMessage': '填写信息以创建您的账号',
+    // AutoSave
+    'autoSave.idle': '已保存',
+    'autoSave.saving': '保存中...',
+    'autoSave.saved': '已保存',
+    'autoSave.error': '保存失败',
+    // Empty states
+    'empty.title': '暂无数据',
+    'empty.description': '没有找到符合条件的记录。',
+    'empty.noMore': '没有更多了',
+    // DevTools
+    'devtools.title': '开发者工具 (Ctrl+Shift+D)',
     // Validation
     'validation.required': '此字段为必填项',
     'validation.minLength': '最少 {min} 个字符',
@@ -128,6 +162,9 @@ const locales: Record<string, Locale> = {
     'common.home': 'Home',
     'common.logout': 'Log out',
     'common.toggleTheme': 'Toggle theme',
+    'common.switchLanguage': 'Switch language',
+    'common.clear': 'Clear',
+    'common.menu': 'Menu',
     'common.darkMode': 'Dark mode',
     'common.lightMode': 'Light mode',
     'common.detail': 'Detail',
@@ -137,19 +174,39 @@ const locales: Record<string, Locale> = {
     'common.retry': 'Retry',
     'common.yes': 'Yes',
     'common.no': 'No',
+    'common.undo': 'Undo',
+    'common.filter': 'Filter',
+    'common.reset': 'Reset',
     'common.welcome': 'Welcome to {title}',
     'common.dashboardHint': 'Select a resource from the sidebar to get started.',
     'common.redirecting': 'Redirecting to login...',
+    'common.expand': 'Expand',
+    'common.collapse': 'Collapse',
+    'common.close': 'Close',
+    'common.copy': 'Copy',
+    'common.copyAll': 'Copy All',
+    'common.copied': 'Copied!',
+    'common.next': 'Next',
+    'common.back': 'Back',
+    'common.step': 'Step',
+    'common.columns': 'Columns',
+    'common.perPage': 'per page',
+    'common.copyId': 'Copy ID',
+    'common.showMore': 'Show more',
+    'common.showLess': 'Show less',
     // Field
     'field.enterValue': 'Enter {label}',
     'field.selectPlaceholder': 'Select...',
     'field.tagsPlaceholder': 'Type a tag and press Enter...',
+    'field.noOptions': 'No options available',
+    'field.addImage': 'Add image',
     // Config errors
     'config.missingEnvTitle': 'Missing Configuration',
     'config.missingEnvDescription': 'The app cannot start because required environment variables are missing.',
     'config.addToEnvFile': 'Add the following to your .env file:',
     'config.envFilePath': 'File path: .env',
-    'config.reload': 'Reload after configuration',
+    'config.reload': 'Refresh page after configuration',
+    'config.reloadButton': 'Reload Page',
     // Auth pages
     'auth.login': 'Login',
     'auth.register': 'Register',
@@ -176,6 +233,17 @@ const locales: Record<string, Locale> = {
     'auth.welcomeMessage': 'Sign in to continue to admin panel',
     'auth.createAccount': 'Create Account',
     'auth.createAccountMessage': 'Fill in your details to create an account',
+    // AutoSave
+    'autoSave.idle': 'Saved',
+    'autoSave.saving': 'Saving...',
+    'autoSave.saved': 'Saved',
+    'autoSave.error': 'Save failed',
+    // Empty states
+    'empty.title': 'No data',
+    'empty.description': 'No records found matching your criteria.',
+    'empty.noMore': 'No more items',
+    // DevTools
+    'devtools.title': 'DevTools (Ctrl+Shift+D)',
     // Validation
     'validation.required': 'This field is required',
     'validation.minLength': 'Minimum {min} characters',

package/src/index.ts

@@ -5,8 +5,8 @@ export {
   setAuthProvider, getAuthProvider,
   setResources, getResources, getResource,
   setRouterProvider, getRouterProvider,
-} from './context';
-export type { DataProviderInput } from './context';
+} from './context.svelte';
+export type { DataProviderInput } from './context.svelte';
 export {
   useList, useInfiniteList,
   useOne, useShow,
@@ -92,3 +92,5 @@ export {
   unionFilters, unionSorters,
   file2Base64, generateDefaultDocumentTitle,
 } from './helpers';
+export { TableState } from './table-state.svelte';
+export type { TableStateOptions } from './table-state.svelte';

package/src/mutation-hooks.svelte.ts

@@ -1,6 +1,6 @@
 import { createMutation, useQueryClient } from '@tanstack/svelte-query';
 import { getAdminOptions } from './options';
-import { getDataProviderForResource } from './context';
+import { getDataProviderForResource } from './context.svelte';
 import { useParsed } from './useParsed';
 import { audit } from './audit';
 import { UndoError } from './types';

package/src/query-hooks.svelte.ts

@@ -1,6 +1,6 @@
 import { createQuery, createInfiniteQuery } from '@tanstack/svelte-query';
 import { getAdminOptions } from './options';
-import { getDataProviderForResource, getDataProvider } from './context';
+import { getDataProviderForResource, getDataProvider, getLiveProvider } from './context.svelte';
 import { useParsed } from './useParsed';
 import {
   createOvertimeTracker,
@@ -64,7 +64,7 @@ export function useList<TData extends BaseRecord = BaseRecord, TError = HttpErro
 
   createLiveSubscription({
     resource,
-    liveProvider: (globalThis as any).__svadminLiveProvider, // Handle via context ideally, or skip if not needed. Wait, in live.ts we pass liveProvider. Let's fix this in hook-utils.
+    liveProvider: getLiveProvider(),
     liveMode: options.liveMode ?? adminOptions.liveMode,
     onLiveEvent: (e) => {
       options.onLiveEvent?.(e);

package/src/routing-hooks.svelte.ts

@@ -1,5 +1,5 @@
 import { currentPath, navigate } from './router';
-import { getResource, getResources, getRouterProvider } from './context';
+import { getResource, getResources, getRouterProvider } from './context.svelte';
 import { useParsed } from './useParsed';
 
 // ─── routing-hooks.svelte.ts ───────────────────────────────────

package/src/table-hooks.svelte.ts

@@ -1,7 +1,7 @@
 import { useParsed } from './useParsed';
 import { useList } from './query-hooks.svelte';
 import { readURLState, writeURLState } from './url-sync';
-import type { Pagination, Sort, Filter, BaseRecord, HttpError, KnownResources } from './types';
+import type { Pagination, Sort, Filter, BaseRecord, HttpError, KnownResources, GetListResult } from './types';
 import type { UseListOptions } from './query-hooks.svelte';
 
 export type FilterSetMode = 'merge' | 'replace';
@@ -148,15 +148,15 @@ export function useTable<
     createLinkForSyncWithLocation,
     get totalPages() {
       // ts-expect-error reactive access
-      const total = (query as any).data?.total ?? 0;
+      const total = (query.data as GetListResult<TQueryFnData> | undefined)?.total ?? 0;
       return Math.ceil(total / (pagination.pageSize ?? 10));
     },
     get current() { return pagination.current ?? 1; },
     get pageSize() { return pagination.pageSize ?? 10; },
-    get pageCount() { return Math.ceil(((query as any).data?.total ?? 0) / (pagination.pageSize ?? 10)); },
+    get pageCount() { return Math.ceil(((query.data as GetListResult<TQueryFnData> | undefined)?.total ?? 0) / (pagination.pageSize ?? 10)); },
     get clientData(): TQueryFnData[] {
       if (paginationMode !== 'client') return [];
-      const allData = ((query as any).data?.data ?? []) as TQueryFnData[];
+      const allData = ((query.data as GetListResult<TQueryFnData> | undefined)?.data ?? []) as TQueryFnData[];
       const start = ((pagination.current ?? 1) - 1) * (pagination.pageSize ?? 10);
       const end = start + (pagination.pageSize ?? 10);
       let sorted = [...allData];

package/src/table-state.svelte.ts

@@ -0,0 +1,243 @@
+// TableState — Svelte 5 Class State Pattern for table data management
+// Reactive class that encapsulates all table state with fine-grained $state/$derived
+
+import { useParsed } from './useParsed';
+import { useList } from './query-hooks.svelte';
+import { readURLState, writeURLState } from './url-sync';
+import type { Pagination, Sort, Filter, BaseRecord, HttpError, KnownResources, GetListResult } from './types';
+import type { UseListOptions } from './query-hooks.svelte';
+
+export type FilterSetMode = 'merge' | 'replace';
+
+export interface TableStateOptions<TData extends BaseRecord = BaseRecord, TError = HttpError>
+  extends Omit<UseListOptions<TData, TError>, 'pagination' | 'sorters' | 'filters'> {
+  resource?: KnownResources;
+  pagination?: Pagination;
+  sorters?: {
+    initial?: Sort[];
+    permanent?: Sort[];
+    mode?: 'off' | 'server';
+  };
+  filters?: {
+    initial?: Filter[];
+    permanent?: Filter[];
+    mode?: 'off' | 'server';
+    defaultBehavior?: FilterSetMode;
+  };
+  syncWithLocation?: boolean;
+}
+
+/**
+ * Svelte 5 Class-based reactive table state.
+ *
+ * Usage:
+ * ```ts
+ * const table = new TableState({ resource: 'posts' });
+ * table.setPage(2);
+ * table.toggleSort('title');
+ * console.log(table.data); // reactive
+ * ```
+ */
+export class TableState<TData extends BaseRecord = BaseRecord, TError = HttpError> {
+  // ─── Reactive state ───────────────────────────────────────────
+  pagination = $state<Pagination>({ current: 1, pageSize: 10 });
+  currentSorters = $state<Sort[]>([]);
+  currentFilters = $state<Filter[]>([]);
+
+  // ─── Private config ───────────────────────────────────────────
+  private permanentSorters: Sort[];
+  private permanentFilters: Filter[];
+  private sortersMode: 'off' | 'server';
+  private filtersMode: 'off' | 'server';
+  private filterDefaultBehavior: FilterSetMode;
+  private syncWithLocation: boolean;
+  private paginationMode: string;
+
+  // ─── Query result ─────────────────────────────────────────────
+  private _queryResult;
+
+  constructor(options: TableStateOptions<TData, TError> = {}) {
+    const parsed = useParsed();
+    const resource = options.resource ?? parsed.resource ?? '';
+
+    this.permanentSorters = options.sorters?.permanent ?? [];
+    this.permanentFilters = options.filters?.permanent ?? [];
+    this.sortersMode = options.sorters?.mode ?? 'server';
+    this.filtersMode = options.filters?.mode ?? 'server';
+    this.filterDefaultBehavior = options.filters?.defaultBehavior ?? 'replace';
+    this.syncWithLocation = options.syncWithLocation ?? false;
+    this.paginationMode = options.pagination?.mode ?? 'server';
+
+    // Init from URL or defaults
+    let initPagination = options.pagination ?? { current: 1, pageSize: 10 };
+    let initSorters = options.sorters?.initial ?? [];
+    let initFilters = options.filters?.initial ?? [];
+
+    if (this.syncWithLocation && typeof window !== 'undefined') {
+      const urlState = readURLState();
+      if (urlState.page || urlState.pageSize) {
+        initPagination = {
+          current: urlState.page ?? initPagination.current,
+          pageSize: urlState.pageSize ?? initPagination.pageSize,
+        };
+      }
+      if (urlState.sortField) {
+        initSorters = [{ field: urlState.sortField, order: (urlState.sortOrder as 'asc' | 'desc') ?? 'asc' }];
+      }
+      if (urlState.filters) {
+        initFilters = urlState.filters;
+      }
+    }
+
+    this.pagination = initPagination;
+    this.currentSorters = initSorters;
+    this.currentFilters = initFilters;
+
+    // Create query
+    const { meta, syncWithLocation: _s, dataProviderName, pagination: _p, sorters: _sr, filters: _f, ...restOptions } = options;
+    this._queryResult = useList<TData, TError>({
+      resource,
+      pagination: this.queryPagination,
+      sorters: this.effectiveSorters,
+      filters: this.effectiveFilters,
+      meta,
+      dataProviderName,
+      ...restOptions,
+    });
+
+    // URL sync effect
+    if (this.syncWithLocation && typeof window !== 'undefined') {
+      $effect(() => {
+        writeURLState({
+          page: this.pagination.current,
+          pageSize: this.pagination.pageSize,
+          sortField: this.effectiveSorters[0]?.field,
+          sortOrder: this.effectiveSorters[0]?.order,
+          filters: this.effectiveFilters,
+        });
+      });
+    }
+  }
+
+  // ─── Derived state ────────────────────────────────────────────
+  get effectiveSorters() { return [...this.currentSorters, ...this.permanentSorters]; }
+  get effectiveFilters() { return [...this.currentFilters, ...this.permanentFilters]; }
+
+  private get queryPagination() {
+    return this.paginationMode === 'server'
+      ? this.pagination
+      : { current: 1, pageSize: 999999, mode: this.paginationMode as 'client' | 'off' };
+  }
+
+  /** Underlying TanStack Query result */
+  get query() { return this._queryResult.query; }
+
+  /** Table data rows */
+  get data(): TData[] { return (this.query.data as GetListResult<TData> | undefined)?.data ?? []; }
+
+  /** Total record count */
+  get total(): number { return (this.query.data as GetListResult<TData> | undefined)?.total ?? 0; }
+
+  /** Is data loading */
+  get isLoading(): boolean { return this.query.isLoading; }
+
+  /** Is data error */
+  get isError(): boolean { return this.query.isError; }
+
+  /** Error object */
+  get error(): TError | null { return this.query.error; }
+
+  /** Current page number */
+  get current(): number { return this.pagination.current ?? 1; }
+
+  /** Page size */
+  get pageSize(): number { return this.pagination.pageSize ?? 10; }
+
+  /** Total number of pages */
+  get pageCount(): number { return Math.ceil(this.total / this.pageSize); }
+
+  /** Has next page */
+  get hasNextPage(): boolean { return this.current < this.pageCount; }
+
+  /** Has previous page */
+  get hasPreviousPage(): boolean { return this.current > 1; }
+
+  // ─── Mutators ─────────────────────────────────────────────────
+  setPage(page: number) {
+    this.pagination = { ...this.pagination, current: page };
+  }
+
+  setPageSize(size: number) {
+    this.pagination = { ...this.pagination, pageSize: size, current: 1 };
+  }
+
+  nextPage() {
+    if (this.hasNextPage) this.setPage(this.current + 1);
+  }
+
+  previousPage() {
+    if (this.hasPreviousPage) this.setPage(this.current - 1);
+  }
+
+  setSorters(newSorters: Sort[]) {
+    this.currentSorters = newSorters;
+  }
+
+  toggleSort(field: string) {
+    const existing = this.currentSorters.find(s => s.field === field);
+    if (!existing) {
+      this.currentSorters = [{ field, order: 'asc' }];
+    } else if (existing.order === 'asc') {
+      this.currentSorters = [{ field, order: 'desc' }];
+    } else {
+      this.currentSorters = [];
+    }
+  }
+
+  setFilters(newFilters: Filter[], mode?: FilterSetMode) {
+    const behavior = mode ?? this.filterDefaultBehavior;
+    if (behavior === 'merge') {
+      const merged = [...this.currentFilters];
+      for (const nf of newFilters) {
+        const idx = merged.findIndex(f => f.field === nf.field && f.operator === nf.operator);
+        if (idx >= 0) {
+          if (nf.value === undefined || nf.value === null || nf.value === '') merged.splice(idx, 1);
+          else merged[idx] = nf;
+        } else if (nf.value !== undefined && nf.value !== null && nf.value !== '') {
+          merged.push(nf);
+        }
+      }
+      this.currentFilters = merged;
+    } else {
+      this.currentFilters = newFilters;
+    }
+    this.pagination = { ...this.pagination, current: 1 };
+  }
+
+  resetFilters() {
+    this.currentFilters = [];
+    this.pagination = { ...this.pagination, current: 1 };
+  }
+
+  /** For client-side pagination mode */
+  get clientData(): TData[] {
+    if (this.paginationMode !== 'client') return [];
+    const allData = this.data;
+    const start = (this.current - 1) * this.pageSize;
+    const end = start + this.pageSize;
+    let sorted = [...allData];
+    const activeSorters = this.sortersMode === 'off' ? this.effectiveSorters : this.currentSorters;
+    if (activeSorters.length > 0) {
+      const { field, order } = activeSorters[0];
+      sorted.sort((a, b) => {
+        const va = (a as Record<string, unknown>)[field];
+        const vb = (b as Record<string, unknown>)[field];
+        if (va == null) return 1;
+        if (vb == null) return -1;
+        const cmp = va < vb ? -1 : va > vb ? 1 : 0;
+        return order === 'desc' ? -cmp : cmp;
+      });
+    }
+    return sorted.slice(start, end);
+  }
+}

package/src/toast.svelte.ts

@@ -1,4 +1,7 @@
-// Toast notification system — Svelte 5 runes-based
+// Toast notification system — wraps svelte-sonner for consistent API
+// Maintains backward-compatible `toast.success()` / `toast.error()` etc.
+
+import { toast as sonner } from 'svelte-sonner';
 
 export type ToastType = 'success' | 'error' | 'info' | 'warning' | 'undoable';
 
@@ -11,6 +14,7 @@ export interface Toast {
   onTimeout?: () => void;
 }
 
+// Legacy compatibility — kept for existing consumers
 let nextId = 0;
 let toasts = $state<Toast[]>([]);
 
@@ -19,23 +23,35 @@ 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
+  if (type !== 'undoable') {
+    switch (type) {
+      case 'success': sonner.success(message, { duration }); break;
+      case 'error': sonner.error(message, { duration }); break;
+      case 'warning': sonner.warning(message, { duration }); break;
+      case 'info': sonner.info(message, { duration }); break;
+    }
+    return;
+  }
+
+  // Undoable toasts still use custom system
   const id = nextId++;
   toasts = [...toasts, { id, type, message, duration, ...options }];
-  if (duration > 0 && type !== 'undoable') {
-    setTimeout(() => removeToast(id), duration);
-  }
 }
 
 export function removeToast(id: number): void {
   toasts = toasts.filter(t => t.id !== id);
 }
 
-// Convenience methods
+// Convenience methods — backward compatible
 export const toast = {
   success: (msg: string, duration?: number) => addToast('success', msg, duration),
   error: (msg: string, duration?: number) => addToast('error', msg, duration ?? 5000),
   info: (msg: string, duration?: number) => addToast('info', msg, duration),
   warning: (msg: string, duration?: number) => addToast('warning', msg, duration ?? 4000),
-  undoable: (msg: string, duration: number, onUndo: () => void, onTimeout: () => void) => 
+  undoable: (msg: string, duration: number, onUndo: () => void, onTimeout: () => void) =>
     addToast('undoable', msg, duration, { onUndo, onTimeout }),
+  /** Promise toast — shows loading → success/error automatically */
+  promise: <T>(promise: Promise<T>, opts: { loading: string; success: string; error: string }) =>
+    sonner.promise(promise, opts),
 };

package/src/types.ts

@@ -255,6 +255,8 @@ export interface ResourceDefinition {
   showInMenu?: boolean;
   parentName?: string;
   menuOrder?: number;
+  /** Navigation group name — resources with the same group are displayed in a collapsible section */
+  group?: string;
   meta?: Record<string, unknown> & { dataProviderName?: string; parent?: string };
 }
 
@@ -266,6 +268,7 @@ export interface FieldDefinition {
   required?: boolean;
   searchable?: boolean;
   sortable?: boolean;
+  filterable?: boolean;
   width?: string;
   showInList?: boolean;
   showInForm?: boolean;
@@ -280,6 +283,8 @@ export interface FieldDefinition {
   optionValue?: string;    // field to use as value
   // Validation
   validate?: (value: unknown) => string | null;
+  // Grouping
+  group?: string;
 }
 
 // ─── Resource Type Registry ───────────────────────────────────

package/src/unsaved-changes.svelte.ts

@@ -1,7 +1,7 @@
 // UnsavedChangesNotifier — warns user before leaving page with unsaved changes
 // Svelte 5 component using runes
 
-import { onDestroy, onMount } from 'svelte';
+// No lifecycle imports needed — uses module-level $state pattern
 
 let warnWhenUnsavedChanges = $state(false);
 

package/src/useParsed.ts

@@ -1,7 +1,7 @@
 // useParsed — parse current URL hash into structured route info
 
 import { currentPath } from './router';
-import { getResources } from './context';
+import { getResources } from './context.svelte';
 
 interface ParsedRoute {
   resource?: string;

package/src/useStepsForm.svelte.ts

@@ -35,7 +35,7 @@ export function useStepsForm<
   TError = HttpError,
   TVariables = Record<string, unknown>,
   TData extends BaseRecord = TQueryFnData
->(options: UseStepsFormOptions<TQueryFnData, TError, TVariables, TData> = {} as any): UseStepsFormResult<TQueryFnData, TError, TVariables, TData> {
+>(options: UseStepsFormOptions<TQueryFnData, TError, TVariables, TData> = {} as UseStepsFormOptions<TQueryFnData, TError, TVariables, TData>): UseStepsFormResult<TQueryFnData, TError, TVariables, TData> {
   const form = useForm<TQueryFnData, TError, TVariables, TData>(options);
   
   let currentStep = $state(options.defaultStep ?? 0);

package/src/utility-hooks.svelte.ts

@@ -1,7 +1,7 @@
 import { useForm, type UseFormOptions } from './form-hooks.svelte';
 import { useQueryClient } from '@tanstack/svelte-query';
 import { useParsed } from './useParsed';
-import { getResource, getResources } from './context';
+import { getResource, getResources } from './context.svelte';
 import { getAdminOptions } from './options';
 import { navigate } from './router';
 import { t } from './i18n.svelte';