@svadmin/core 0.0.1

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@svadmin/core",
+  "version": "0.0.1",
+  "description": "Core SDK — hooks, types, context, i18n, permissions, router",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "src/**/*"
+  ],
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./router": {
+      "types": "./src/router.ts",
+      "default": "./src/router.ts"
+    },
+    "./i18n": {
+      "types": "./src/i18n.svelte.ts",
+      "default": "./src/i18n.svelte.ts"
+    },
+    "./permissions": {
+      "types": "./src/permissions.ts",
+      "default": "./src/permissions.ts"
+    },
+    "./toast": {
+      "types": "./src/toast.svelte.ts",
+      "default": "./src/toast.svelte.ts"
+    },
+    "./audit": {
+      "types": "./src/audit.ts",
+      "default": "./src/audit.ts"
+    },
+    "./live": {
+      "types": "./src/live.ts",
+      "default": "./src/live.ts"
+    },
+    "./theme": {
+      "types": "./src/theme.svelte.ts",
+      "default": "./src/theme.svelte.ts"
+    }
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0",
+    "@tanstack/svelte-query": "^6.0.0"
+  },
+  "license": "MIT",
+  "author": "zuohuadong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zuohuadong/svadmin.git"
+  },
+  "homepage": "https://github.com/zuohuadong/svadmin#readme",
+  "bugs": {
+    "url": "https://github.com/zuohuadong/svadmin/issues"
+  }
+}

package/src/audit.ts

@@ -0,0 +1,29 @@
+// Audit logging — record admin operations
+
+export interface AuditEntry {
+  timestamp: string;
+  action: 'create' | 'update' | 'delete' | 'login' | 'logout';
+  resource?: string;
+  recordId?: string | number;
+  userId?: string;
+  details?: Record<string, unknown>;
+}
+
+export type AuditHandler = (entry: AuditEntry) => void | Promise<void>;
+
+let handler: AuditHandler = (entry) => {
+  console.info('[audit]', entry.action, entry.resource, entry.recordId);
+};
+
+export function setAuditHandler(fn: AuditHandler): void {
+  handler = fn;
+}
+
+export function audit(entry: Omit<AuditEntry, 'timestamp'>): void {
+  const fullEntry: AuditEntry = { ...entry, timestamp: new Date().toISOString() };
+  try {
+    handler(fullEntry);
+  } catch (e) {
+    console.error('[audit] handler error:', e);
+  }
+}

package/src/context.ts

@@ -0,0 +1,49 @@
+// Svelte context — provides DataProvider, AuthProvider, and Resources to all components
+
+import { getContext, setContext } from 'svelte';
+import type { DataProvider, AuthProvider, ResourceDefinition } from './types';
+
+const DATA_PROVIDER_KEY = Symbol('data-provider');
+const AUTH_PROVIDER_KEY = Symbol('auth-provider');
+const RESOURCES_KEY = Symbol('resources');
+
+// ─── Setters (called once in App.svelte) ────────────────────────
+
+export function setDataProvider(provider: DataProvider): void {
+  setContext(DATA_PROVIDER_KEY, provider);
+}
+
+export function setAuthProvider(provider: AuthProvider): void {
+  setContext(AUTH_PROVIDER_KEY, provider);
+}
+
+export function setResources(resources: ResourceDefinition[]): void {
+  setContext(RESOURCES_KEY, resources);
+}
+
+// ─── Getters (called from any child component) ──────────────────
+
+export function getDataProvider(): DataProvider {
+  const provider = getContext<DataProvider>(DATA_PROVIDER_KEY);
+  if (!provider) throw new Error('DataProvider not found. Did you call setDataProvider in App.svelte?');
+  return 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;
+}
+
+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?');
+  return resources;
+}
+
+export function getResource(name: string): ResourceDefinition {
+  const resources = getResources();
+  const resource = resources.find(r => r.name === name);
+  if (!resource) throw new Error(`Resource "${name}" not found in resource definitions.`);
+  return resource;
+}

package/src/hooks.svelte.ts

@@ -0,0 +1,513 @@
+// Complete CRUD hooks — 100% Refine-compatible
+// TanStack Query v6 (Svelte 5 runes-native) wrappers
+
+import {
+  createQuery,
+  createMutation,
+  createInfiniteQuery,
+  useQueryClient,
+} from '@tanstack/svelte-query';
+import { getDataProvider } from './context';
+import type { GetListResult, Sort, Filter, Pagination, MutationMode } from './types';
+import { toast } from './toast.svelte';
+import { audit } from './audit';
+import { navigate } from './router';
+import { t } from './i18n.svelte';
+
+// ─── useList ────────────────────────────────────────────────────
+
+interface UseListOptions {
+  resource: string;
+  pagination?: Pagination;
+  sorters?: Sort[];
+  filters?: Filter[];
+  meta?: Record<string, unknown>;
+  enabled?: boolean;
+}
+
+export function useList<T = Record<string, unknown>>(options: UseListOptions) {
+  const provider = getDataProvider();
+  const { resource, pagination, sorters, filters, meta, enabled = true } = options;
+
+  return createQuery<GetListResult<T>>(() => ({
+    queryKey: [resource, 'list', { pagination, sorters, filters }],
+    queryFn: () => provider.getList<T>({ resource, pagination, sorters, filters, meta }),
+    enabled,
+  }));
+}
+
+// ─── useInfiniteList ────────────────────────────────────────────
+
+interface UseInfiniteListOptions {
+  resource: string;
+  pageSize?: number;
+  sorters?: Sort[];
+  filters?: Filter[];
+  meta?: Record<string, unknown>;
+  enabled?: boolean;
+}
+
+export function useInfiniteList<T = Record<string, unknown>>(options: UseInfiniteListOptions) {
+  const provider = getDataProvider();
+  const { resource, pageSize = 10, sorters, filters, meta, enabled = true } = options;
+
+  return createInfiniteQuery<GetListResult<T>>(() => ({
+    queryKey: [resource, 'infinite', { sorters, filters }],
+    queryFn: ({ pageParam = 1 }) =>
+      provider.getList<T>({
+        resource,
+        pagination: { current: pageParam as number, pageSize },
+        sorters,
+        filters,
+        meta,
+      }),
+    initialPageParam: 1,
+    getNextPageParam: (lastPage, allPages) => {
+      const totalFetched = allPages.reduce((sum, p) => sum + p.data.length, 0);
+      return totalFetched < lastPage.total ? allPages.length + 1 : undefined;
+    },
+    enabled,
+  }));
+}
+
+// ─── useOne ─────────────────────────────────────────────────────
+
+interface UseOneOptions {
+  resource: string;
+  id: string | number;
+  meta?: Record<string, unknown>;
+  enabled?: boolean;
+}
+
+export function useOne<T = Record<string, unknown>>(options: UseOneOptions) {
+  const provider = getDataProvider();
+  const { resource, id, meta, enabled = true } = options;
+
+  return createQuery(() => ({
+    queryKey: [resource, 'one', id],
+    queryFn: async () => {
+      const result = await provider.getOne<T>({ resource, id, meta });
+      return result.data;
+    },
+    enabled: enabled && id != null,
+  }));
+}
+
+// ─── useShow (alias for useOne with route awareness) ────────────
+
+export function useShow<T = Record<string, unknown>>(options: UseOneOptions) {
+  return useOne<T>(options);
+}
+
+// ─── useSelect ──────────────────────────────────────────────────
+
+interface UseSelectOptions {
+  resource: string;
+  optionLabel?: string;
+  optionValue?: string;
+  filters?: Filter[];
+  sorters?: Sort[];
+  enabled?: boolean;
+}
+
+export function useSelect(options: UseSelectOptions) {
+  const provider = getDataProvider();
+  const {
+    resource, optionLabel = 'name', optionValue = 'id',
+    filters, sorters, enabled = true,
+  } = options;
+
+  return createQuery(() => ({
+    queryKey: [resource, 'select', { optionLabel, optionValue, filters }],
+    queryFn: async () => {
+      const result = await provider.getList({ resource, pagination: { current: 1, pageSize: 1000 }, filters, sorters });
+      return result.data.map(item => ({
+        label: String(item[optionLabel] ?? ''),
+        value: String(item[optionValue] ?? ''),
+      }));
+    },
+    enabled,
+    staleTime: 10 * 60 * 1000,
+  }));
+}
+
+// ─── useMany ────────────────────────────────────────────────────
+
+interface UseManyOptions {
+  resource: string;
+  ids: (string | number)[];
+  meta?: Record<string, unknown>;
+  enabled?: boolean;
+}
+
+export function useMany<T = Record<string, unknown>>(options: UseManyOptions) {
+  const provider = getDataProvider();
+  const { resource, ids, meta, enabled = true } = options;
+
+  return createQuery(() => ({
+    queryKey: [resource, 'many', ids],
+    queryFn: async () => {
+      if (provider.getMany) {
+        const result = await provider.getMany<T>({ resource, ids, meta });
+        return result.data;
+      }
+      const results = await Promise.all(ids.map(id => provider.getOne<T>({ resource, id, meta })));
+      return results.map(r => r.data);
+    },
+    enabled: enabled && ids.length > 0,
+  }));
+}
+
+// ─── useCustom ──────────────────────────────────────────────────
+
+interface UseCustomQueryOptions<T = unknown> {
+  queryKey: unknown[];
+  queryFn: () => Promise<T>;
+  enabled?: boolean;
+}
+
+export function useCustom<T = unknown>(options: UseCustomQueryOptions<T>) {
+  return createQuery(() => ({
+    queryKey: options.queryKey,
+    queryFn: options.queryFn,
+    enabled: options.enabled ?? true,
+  }));
+}
+
+// ─── useApiUrl ──────────────────────────────────────────────────
+
+export function useApiUrl(): string {
+  const provider = getDataProvider();
+  return provider.getApiUrl();
+}
+
+// ─── useNavigation ──────────────────────────────────────────────
+
+export function useNavigation() {
+  return {
+    list: (resource: string) => navigate(`/${resource}`),
+    create: (resource: string) => navigate(`/${resource}/create`),
+    edit: (resource: string, id: string | number) => navigate(`/${resource}/edit/${id}`),
+    show: (resource: string, id: string | number) => navigate(`/${resource}/show/${id}`),
+    goBack: () => history.back(),
+    push: (path: string) => navigate(path),
+  };
+}
+
+// ─── useResource ────────────────────────────────────────────────
+
+export { getResource as useResource } from './context';
+
+// ─── Mutation options ───────────────────────────────────────────
+
+interface UseMutationOptions {
+  showToast?: boolean;
+  auditLog?: boolean;
+  mutationMode?: MutationMode;
+}
+
+// ─── useCreate ──────────────────────────────────────────────────
+
+export function useCreate<T = Record<string, unknown>>(resource: string, opts?: UseMutationOptions) {
+  const provider = getDataProvider();
+  const queryClient = useQueryClient();
+  const { showToast = true, auditLog = true, mutationMode = 'pessimistic' } = opts ?? {};
+
+  return createMutation(() => ({
+    mutationFn: (variables: Record<string, unknown>) =>
+      provider.create<T>({ resource, variables }),
+    onMutate: mutationMode === 'optimistic'
+      ? async (_variables: Record<string, unknown>) => {
+          await queryClient.cancelQueries({ queryKey: [resource] });
+          const previousData = queryClient.getQueryData([resource, 'list']);
+          return { previousData };
+        }
+      : undefined,
+    onSuccess: (data: { data: T }) => {
+      queryClient.invalidateQueries({ queryKey: [resource] });
+      if (showToast) toast.success(t('common.createSuccess'));
+      if (auditLog) {
+        const record = data.data as Record<string, unknown>;
+        audit({ action: 'create', resource, recordId: record.id as string });
+      }
+    },
+    onError: (error: Error, _variables: Record<string, unknown>, context: { previousData?: unknown } | undefined) => {
+      if (mutationMode === 'optimistic' && context?.previousData) {
+        queryClient.setQueryData([resource, 'list'], context.previousData);
+      }
+      if (showToast) toast.error(t('common.operationFailed') + ': ' + error.message);
+    },
+  }));
+}
+
+// ─── useCreateMany ──────────────────────────────────────────────
+
+export function useCreateMany<T = Record<string, unknown>>(resource: string, opts?: UseMutationOptions) {
+  const provider = getDataProvider();
+  const queryClient = useQueryClient();
+  const { showToast = true, auditLog = true } = opts ?? {};
+
+  return createMutation(() => ({
+    mutationFn: async (variables: Record<string, unknown>[]) => {
+      if (provider.createMany) {
+        return provider.createMany<T>({ resource, variables });
+      }
+      const results = await Promise.all(variables.map(v => provider.create<T>({ resource, variables: v })));
+      return { data: results.map(r => r.data) };
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [resource] });
+      if (showToast) toast.success(t('common.createSuccess'));
+      if (auditLog) audit({ action: 'create', resource, details: { batch: true } });
+    },
+    onError: (error: Error) => {
+      if (showToast) toast.error(t('common.operationFailed') + ': ' + error.message);
+    },
+  }));
+}
+
+// ─── useUpdate ──────────────────────────────────────────────────
+
+interface UpdateVariables {
+  id: string | number;
+  variables: Record<string, unknown>;
+}
+
+export function useUpdate<T = Record<string, unknown>>(resource: string, opts?: UseMutationOptions) {
+  const provider = getDataProvider();
+  const queryClient = useQueryClient();
+  const { showToast = true, auditLog = true, mutationMode = 'pessimistic' } = opts ?? {};
+
+  return createMutation<{ data: T }, Error, UpdateVariables>(() => ({
+    mutationFn: ({ id, variables }: UpdateVariables) =>
+      provider.update<T>({ resource, id, variables }),
+    onMutate: mutationMode === 'optimistic'
+      ? async ({ id }: UpdateVariables) => {
+          await queryClient.cancelQueries({ queryKey: [resource, 'one', id] });
+          const previousData = queryClient.getQueryData([resource, 'one', id]);
+          return { previousData };
+        }
+      : undefined,
+    onSuccess: (_data: { data: T }, vars: UpdateVariables) => {
+      queryClient.invalidateQueries({ queryKey: [resource] });
+      if (showToast) toast.success(t('common.updateSuccess'));
+      if (auditLog) audit({ action: 'update', resource, recordId: vars.id });
+    },
+    onError: (error: Error) => {
+      if (showToast) toast.error(t('common.operationFailed') + ': ' + error.message);
+    },
+  }));
+}
+
+// ─── useUpdateMany ──────────────────────────────────────────────
+
+export function useUpdateMany<T = Record<string, unknown>>(resource: string, opts?: UseMutationOptions) {
+  const provider = getDataProvider();
+  const queryClient = useQueryClient();
+  const { showToast = true, auditLog = true } = opts ?? {};
+
+  return createMutation(() => ({
+    mutationFn: async ({ ids, variables }: { ids: (string | number)[]; variables: Record<string, unknown> }) => {
+      if (provider.updateMany) {
+        return provider.updateMany<T>({ resource, ids, variables });
+      }
+      const results = await Promise.all(ids.map(id => provider.update<T>({ resource, id, variables })));
+      return { data: results.map(r => r.data) };
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [resource] });
+      if (showToast) toast.success(t('common.updateSuccess'));
+      if (auditLog) audit({ action: 'update', resource, details: { batch: true } });
+    },
+    onError: (error: Error) => {
+      if (showToast) toast.error(t('common.operationFailed') + ': ' + error.message);
+    },
+  }));
+}
+
+// ─── useDelete ──────────────────────────────────────────────────
+
+export function useDelete(resource: string, opts?: UseMutationOptions) {
+  const provider = getDataProvider();
+  const queryClient = useQueryClient();
+  const { showToast = true, auditLog = true, mutationMode = 'pessimistic' } = opts ?? {};
+
+  return createMutation(() => ({
+    mutationFn: (id: string | number) =>
+      provider.deleteOne({ resource, id }),
+    onMutate: mutationMode === 'optimistic'
+      ? async (_id: string | number) => {
+          await queryClient.cancelQueries({ queryKey: [resource] });
+          const previousData = queryClient.getQueryData([resource, 'list']);
+          return { previousData };
+        }
+      : undefined,
+    onSuccess: (_data: unknown, id: string | number) => {
+      queryClient.invalidateQueries({ queryKey: [resource] });
+      if (showToast) toast.success(t('common.deleteSuccess'));
+      if (auditLog) audit({ action: 'delete', resource, recordId: id });
+    },
+    onError: (error: Error) => {
+      if (showToast) toast.error(t('common.operationFailed') + ': ' + error.message);
+    },
+  }));
+}
+
+// ─── useDeleteMany ──────────────────────────────────────────────
+
+export function useDeleteMany(resource: string, opts?: UseMutationOptions) {
+  const provider = getDataProvider();
+  const queryClient = useQueryClient();
+  const { showToast = true, auditLog = true } = opts ?? {};
+
+  return createMutation(() => ({
+    mutationFn: async (ids: (string | number)[]) => {
+      if (provider.deleteMany) {
+        return provider.deleteMany({ resource, ids });
+      }
+      const results = await Promise.all(ids.map(id => provider.deleteOne({ resource, id })));
+      return { data: results.map(r => r.data) };
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: [resource] });
+      if (showToast) toast.success(t('common.deleteSuccess'));
+      if (auditLog) audit({ action: 'delete', resource, details: { batch: true } });
+    },
+    onError: (error: Error) => {
+      if (showToast) toast.error(t('common.operationFailed') + ': ' + error.message);
+    },
+  }));
+}
+
+// ─── useForm ────────────────────────────────────────────────────
+// Standalone form hook (like Refine's useForm)
+
+interface UseFormOptions {
+  resource: string;
+  action: 'create' | 'edit' | 'clone';
+  id?: string | number;
+  redirect?: 'list' | 'edit' | 'show' | false;
+  mutationMode?: MutationMode;
+  onMutationSuccess?: (data: unknown) => void;
+  onMutationError?: (error: Error) => void;
+  meta?: Record<string, unknown>;
+}
+
+export function useForm<T = Record<string, unknown>>(options: UseFormOptions) {
+  const provider = getDataProvider();
+  const queryClient = useQueryClient();
+  const { resource, action, id, redirect = 'list', onMutationSuccess, onMutationError, meta } = options;
+
+  // Fetch existing data for edit/clone
+  const query = (action === 'edit' || action === 'clone') && id != null
+    ? createQuery(() => ({
+        queryKey: [resource, 'one', id],
+        queryFn: async () => {
+          const result = await provider.getOne<T>({ resource, id, meta });
+          return result.data;
+        },
+        enabled: id != null,
+      }))
+    : null;
+
+  const createMut = createMutation(() => ({
+    mutationFn: (variables: Record<string, unknown>) =>
+      provider.create<T>({ resource, variables }),
+    onSuccess: (data: { data: T }) => {
+      queryClient.invalidateQueries({ queryKey: [resource] });
+      toast.success(t('common.createSuccess'));
+      const record = data.data as Record<string, unknown>;
+      audit({ action: 'create', resource, recordId: record.id as string });
+      onMutationSuccess?.(data);
+      handleRedirect();
+    },
+    onError: (error: Error) => {
+      toast.error(t('common.operationFailed') + ': ' + error.message);
+      onMutationError?.(error);
+    },
+  }));
+
+  const updateMut = createMutation(() => ({
+    mutationFn: (variables: Record<string, unknown>) =>
+      provider.update<T>({ resource, id: id!, variables }),
+    onSuccess: (data: { data: T }) => {
+      queryClient.invalidateQueries({ queryKey: [resource] });
+      toast.success(t('common.updateSuccess'));
+      audit({ action: 'update', resource, recordId: id });
+      onMutationSuccess?.(data);
+      handleRedirect();
+    },
+    onError: (error: Error) => {
+      toast.error(t('common.operationFailed') + ': ' + error.message);
+      onMutationError?.(error);
+    },
+  }));
+
+  function handleRedirect() {
+    if (redirect === 'list') navigate(`/${resource}`);
+    else if (redirect === 'edit' && id) navigate(`/${resource}/edit/${id}`);
+    else if (redirect === 'show' && id) navigate(`/${resource}/show/${id}`);
+  }
+
+  async function onFinish(values: Record<string, unknown>) {
+    if (action === 'create' || action === 'clone') {
+      // @ts-expect-error $ rune prefix — Svelte compiler transforms this
+      await $createMut.mutateAsync(values);
+    } else {
+      // @ts-expect-error $ rune prefix — Svelte compiler transforms this
+      await $updateMut.mutateAsync(values);
+    }
+  }
+
+  return {
+    query,
+    get formLoading() {
+      // @ts-expect-error $ rune prefix — Svelte compiler transforms this
+      return (query ? $query?.isLoading : false) || $createMut.isPending || $updateMut.isPending;
+    },
+    mutation: action === 'edit' ? updateMut : createMut,
+    onFinish,
+  };
+}
+
+// ─── useTable ───────────────────────────────────────────────────
+// Standalone table hook (like Refine's useTable)
+
+interface UseTableOptions {
+  resource: string;
+  pagination?: Pagination;
+  sorters?: Sort[];
+  filters?: Filter[];
+  syncWithLocation?: boolean;
+  meta?: Record<string, unknown>;
+}
+
+export function useTable<T = Record<string, unknown>>(options: UseTableOptions) {
+  const { resource, meta } = options;
+
+  let pagination = $state<Pagination>(options.pagination ?? { current: 1, pageSize: 10 });
+  let sorters = $state<Sort[]>(options.sorters ?? []);
+  let filters = $state<Filter[]>(options.filters ?? []);
+
+  const query = useList<T>({ resource, pagination, sorters, filters, meta });
+
+  function setSorters(newSorters: Sort[]) { sorters = newSorters; }
+  function setFilters(newFilters: Filter[]) { filters = newFilters; }
+  function setPage(page: number) { pagination = { ...pagination, current: page }; }
+  function setPageSize(size: number) { pagination = { ...pagination, pageSize: size, current: 1 }; }
+
+  return {
+    query,
+    pagination,
+    sorters,
+    filters,
+    setSorters,
+    setFilters,
+    setPage,
+    setPageSize,
+    get totalPages() {
+      // @ts-expect-error $ rune prefix — Svelte compiler transforms this
+      return Math.ceil(($query.data?.total ?? 0) / (pagination.pageSize ?? 10));
+    },
+  };
+}

package/src/i18n.svelte.ts

@@ -0,0 +1,157 @@
+// Minimal i18n — simple key-value translation
+
+type Locale = Record<string, string>;
+
+const locales: Record<string, Locale> = {
+  'zh-CN': {
+    // Common
+    'common.save': '保存',
+    'common.cancel': '取消',
+    'common.create': '新建',
+    'common.edit': '编辑',
+    'common.delete': '删除',
+    'common.search': '搜索...',
+    'common.confirm': '确定',
+    'common.loading': '加载中...',
+    'common.noData': '暂无数据',
+    'common.actions': '操作',
+    'common.total': '共 {total} 条',
+    'common.page': '{current} / {total}',
+    'common.export': '导出',
+    'common.import': '导入',
+    'common.selectAll': '全选',
+    'common.batchDelete': '批量删除 ({count})',
+    'common.unsavedChanges': '有未保存的修改，确定离开吗？',
+    'common.unsaved': '未保存',
+    'common.deleteConfirm': '确定要删除这条记录吗？此操作不可撤销。',
+    'common.batchDeleteConfirm': '确定要删除选中的 {count} 条记录吗？此操作不可撤销。',
+    'common.confirmAction': '确认操作',
+    'common.operationSuccess': '操作成功',
+    'common.operationFailed': '操作失败',
+    'common.createSuccess': '创建成功',
+    'common.updateSuccess': '更新成功',
+    'common.deleteSuccess': '删除成功',
+    'common.loginFailed': '登录失败',
+    'common.home': '首页',
+    'common.logout': '退出登录',
+    'common.toggleTheme': '切换主题',
+    'common.darkMode': '暗色模式',
+    'common.lightMode': '亮色模式',
+    'common.noData': '暂无数据',
+    'common.search': '搜索...',
+    'common.detail': '详情',
+    'common.loadFailed': '加载失败: {message}',
+    'common.pageNotFound': '页面未找到',
+    'common.error': '出错了',
+    'common.retry': '重试',
+    'common.yes': '是',
+    'common.no': '否',
+    // Field
+    'field.enterValue': '输入{label}',
+    'field.selectPlaceholder': '请选择',
+    'field.tagsPlaceholder': '输入标签后按回车...',
+    // Config errors
+    'config.missingEnvTitle': '环境配置缺失',
+    'config.missingEnvDescription': '应用无法启动，因为缺少必要的环境变量。',
+    'config.addToEnvFile': '请在 .env 文件中添加以下内容：',
+    'config.envFilePath': '文件路径: .env',
+    'config.reload': '配置完成后刷新页面',
+  },
+  'en': {
+    // Common
+    'common.save': 'Save',
+    'common.cancel': 'Cancel',
+    'common.create': 'Create',
+    'common.edit': 'Edit',
+    'common.delete': 'Delete',
+    'common.search': 'Search...',
+    'common.confirm': 'Confirm',
+    'common.loading': 'Loading...',
+    'common.noData': 'No data',
+    'common.actions': 'Actions',
+    'common.total': 'Total: {total}',
+    'common.page': '{current} / {total}',
+    'common.export': 'Export',
+    'common.import': 'Import',
+    'common.selectAll': 'Select All',
+    'common.batchDelete': 'Batch Delete ({count})',
+    'common.unsavedChanges': 'You have unsaved changes. Leave anyway?',
+    'common.unsaved': 'Unsaved',
+    'common.deleteConfirm': 'Are you sure you want to delete this record? This cannot be undone.',
+    'common.batchDeleteConfirm': 'Delete {count} selected records? This cannot be undone.',
+    'common.confirmAction': 'Confirm Action',
+    'common.operationSuccess': 'Operation successful',
+    'common.operationFailed': 'Operation failed',
+    'common.createSuccess': 'Created successfully',
+    'common.updateSuccess': 'Updated successfully',
+    'common.deleteSuccess': 'Deleted successfully',
+    'common.loginFailed': 'Login failed',
+    'common.home': 'Home',
+    'common.logout': 'Log out',
+    'common.toggleTheme': 'Toggle theme',
+    'common.darkMode': 'Dark mode',
+    'common.lightMode': 'Light mode',
+    'common.noData': 'No data',
+    'common.search': 'Search...',
+    'common.detail': 'Detail',
+    'common.loadFailed': 'Load failed: {message}',
+    'common.pageNotFound': 'Page not found',
+    'common.error': 'Something went wrong',
+    'common.retry': 'Retry',
+    'common.yes': 'Yes',
+    'common.no': 'No',
+    // Field
+    'field.enterValue': 'Enter {label}',
+    'field.selectPlaceholder': 'Select...',
+    'field.tagsPlaceholder': 'Type a tag and press Enter...',
+    // 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',
+  },
+};
+
+/** Detect best locale from browser language */
+function detectLocale(): string {
+  const browserLang = navigator.language || navigator.languages?.[0] || 'zh-CN';
+  // Exact match
+  if (locales[browserLang]) return browserLang;
+  // Prefix match (e.g., 'zh' → 'zh-CN', 'en-US' → 'en')
+  const prefix = browserLang.split('-')[0];
+  for (const key of Object.keys(locales)) {
+    if (key.startsWith(prefix)) return key;
+  }
+  return 'en';
+}
+
+let currentLocale = $state(detectLocale());
+
+export function setLocale(locale: string): void {
+  currentLocale = locale;
+}
+
+export function getLocale(): string {
+  return currentLocale;
+}
+
+export function getAvailableLocales(): string[] {
+  return Object.keys(locales);
+}
+
+export function t(key: string, params?: Record<string, string | number>): string {
+  const locale = locales[currentLocale] ?? locales['en'];
+  let text = locale[key] ?? key;
+
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      text = text.replace(`{${k}}`, String(v));
+    }
+  }
+  return text;
+}
+
+export function addTranslations(locale: string, translations: Record<string, string>): void {
+  locales[locale] = { ...locales[locale], ...translations };
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+// Core barrel exports
+
+export {
+  setDataProvider, getDataProvider,
+  setAuthProvider, getAuthProvider,
+  setResources, getResources, getResource,
+} from './context';
+export {
+  useList, useInfiniteList,
+  useOne, useShow,
+  useSelect, useMany,
+  useCustom, useApiUrl,
+  useCreate, useCreateMany,
+  useUpdate, useUpdateMany,
+  useDelete, useDeleteMany,
+  useForm, useTable,
+  useNavigation,
+  useResource,
+} from './hooks.svelte';
+export { matchRoute, navigate, currentPath } from './router';
+export { readURLState, writeURLState } from './url-sync';
+export { setAccessControl, canAccess, canAccessAsync } from './permissions';
+export { useLive } from './live';
+export { toast } from './toast.svelte';
+export { t, setLocale, getLocale, getAvailableLocales, addTranslations } from './i18n.svelte';
+export { audit, setAuditHandler } from './audit';
+export { getTheme, setTheme, toggleTheme, getResolvedTheme } from './theme.svelte';
+export type { ThemeMode } from './theme.svelte';
+
+export type {
+  DataProvider, AuthProvider, NotificationProvider, MutationMode,
+  GetListParams, GetListResult,
+  GetOneParams, GetOneResult,
+  GetManyParams, GetManyResult,
+  CreateParams, CreateResult,
+  CreateManyParams, CreateManyResult,
+  UpdateParams, UpdateResult,
+  UpdateManyParams, UpdateManyResult,
+  DeleteParams, DeleteResult,
+  DeleteManyParams, DeleteManyResult,
+  CustomParams, CustomResult,
+  Pagination, Sort, Filter, Identity,
+  ResourceDefinition, FieldDefinition,
+  AuthActionResult, CheckResult,
+} from './types';
+export type { LiveProvider, LiveEvent } from './live';
+export type { Action, AccessControlResult, AccessControlFn } from './permissions';
+export type { AuditEntry, AuditHandler } from './audit';

package/src/live.ts

@@ -0,0 +1,28 @@
+// LiveProvider — Real-time subscription interface + useLive hook
+
+import { useQueryClient } from '@tanstack/svelte-query';
+
+export interface LiveProvider {
+  subscribe(params: { resource: string; callback: (event: LiveEvent) => void }): () => void;
+}
+
+export interface LiveEvent {
+  type: 'INSERT' | 'UPDATE' | 'DELETE';
+  resource: string;
+  payload: Record<string, unknown>;
+}
+
+// Hook to auto-invalidate queries on real-time changes
+export function useLive(liveProvider: LiveProvider, resource: string): void {
+  const queryClient = useQueryClient();
+
+  $effect(() => {
+    const unsubscribe = liveProvider.subscribe({
+      resource,
+      callback: () => {
+        queryClient.invalidateQueries({ queryKey: [resource] });
+      },
+    });
+    return unsubscribe;
+  });
+}

package/src/permissions.ts

@@ -0,0 +1,42 @@
+// Permission / Access Control
+
+
+export type Action = 'list' | 'create' | 'edit' | 'delete' | 'export';
+
+export interface AccessControlResult {
+  can: boolean;
+  reason?: string;
+}
+
+export type AccessControlFn = (
+  resource: string,
+  action: Action,
+  params?: Record<string, unknown>,
+) => AccessControlResult | Promise<AccessControlResult>;
+
+let accessControlFn: AccessControlFn | null = null;
+
+export function setAccessControl(fn: AccessControlFn): void {
+  accessControlFn = fn;
+}
+
+export function canAccess(resource: string, action: Action, params?: Record<string, unknown>): AccessControlResult {
+  if (!accessControlFn) return { can: true };
+  const result = accessControlFn(resource, action, params);
+  if (result instanceof Promise) {
+    console.warn('[permissions] canAccess called synchronously but accessControlFn returned a Promise. Defaulting to { can: true }. Use canAccessAsync() instead.');
+    return { can: true };
+  }
+  return result;
+}
+
+export async function canAccessAsync(resource: string, action: Action, params?: Record<string, unknown>): Promise<AccessControlResult> {
+  if (!accessControlFn) return { can: true };
+  return accessControlFn(resource, action, params);
+}
+
+// Example usage:
+// setAccessControl((resource, action) => {
+//   if (resource === 'users' && action === 'delete') return { can: false, reason: '无权删除用户' };
+//   return { can: true };
+// });

package/src/router.ts

@@ -0,0 +1,46 @@
+// Minimal hash router for Svelte 5 runes mode
+
+interface RouteMatch {
+  route: string;
+  params: Record<string, string>;
+}
+
+// Parse route pattern like /products/edit/:id into regex
+function compileRoute(pattern: string): { regex: RegExp; keys: string[] } {
+  const keys: string[] = [];
+  const regexStr = pattern
+    .replace(/:(\w+)/g, (_, key) => {
+      keys.push(key);
+      return '([^/]+)';
+    })
+    .replace(/\//g, '\\/');
+  return { regex: new RegExp(`^${regexStr}$`), keys };
+}
+
+export function matchRoute(
+  hash: string,
+  routes: string[]
+): RouteMatch | null {
+  const path = hash.replace(/^#/, '') || '/';
+
+  for (const pattern of routes) {
+    const { regex, keys } = compileRoute(pattern);
+    const match = path.match(regex);
+    if (match) {
+      const params: Record<string, string> = {};
+      keys.forEach((key, i) => {
+        params[key] = match[i + 1];
+      });
+      return { route: pattern, params };
+    }
+  }
+  return null;
+}
+
+export function navigate(path: string): void {
+  window.location.hash = path;
+}
+
+export function currentPath(): string {
+  return window.location.hash.replace(/^#/, '') || '/';
+}

package/src/theme.svelte.ts

@@ -0,0 +1,56 @@
+// Theme — dark/light/system mode management (Svelte 5 runes)
+
+export type ThemeMode = 'light' | 'dark' | 'system';
+
+const STORAGE_KEY = 'svadmin-theme';
+
+function getStoredTheme(): ThemeMode {
+  if (typeof localStorage === 'undefined') return 'system';
+  return (localStorage.getItem(STORAGE_KEY) as ThemeMode) ?? 'system';
+}
+
+function getSystemPreference(): 'light' | 'dark' {
+  if (typeof window === 'undefined') return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+let mode = $state<ThemeMode>(getStoredTheme());
+
+function applyTheme(m: ThemeMode): void {
+  const resolved = m === 'system' ? getSystemPreference() : m;
+  if (typeof document !== 'undefined') {
+    document.documentElement.classList.toggle('dark', resolved === 'dark');
+  }
+}
+
+// Apply on init
+applyTheme(mode);
+
+// Listen for system preference changes
+if (typeof window !== 'undefined') {
+  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
+    if (mode === 'system') applyTheme('system');
+  });
+}
+
+export function getTheme(): ThemeMode {
+  return mode;
+}
+
+export function setTheme(newMode: ThemeMode): void {
+  mode = newMode;
+  if (typeof localStorage !== 'undefined') {
+    localStorage.setItem(STORAGE_KEY, newMode);
+  }
+  applyTheme(newMode);
+}
+
+export function toggleTheme(): void {
+  const resolved = mode === 'system' ? getSystemPreference() : mode;
+  setTheme(resolved === 'dark' ? 'light' : 'dark');
+}
+
+/** Resolved theme (always 'light' or 'dark', never 'system') */
+export function getResolvedTheme(): 'light' | 'dark' {
+  return mode === 'system' ? getSystemPreference() : mode;
+}

package/src/toast.svelte.ts

@@ -0,0 +1,37 @@
+// Toast notification system — Svelte 5 runes-based
+
+export type ToastType = 'success' | 'error' | 'info' | 'warning';
+
+export interface Toast {
+  id: number;
+  type: ToastType;
+  message: string;
+  duration: number;
+}
+
+let nextId = 0;
+let toasts = $state<Toast[]>([]);
+
+export function getToasts(): Toast[] {
+  return toasts;
+}
+
+export function addToast(type: ToastType, message: string, duration = 3000): void {
+  const id = nextId++;
+  toasts = [...toasts, { id, type, message, duration }];
+  if (duration > 0) {
+    setTimeout(() => removeToast(id), duration);
+  }
+}
+
+export function removeToast(id: number): void {
+  toasts = toasts.filter(t => t.id !== id);
+}
+
+// Convenience methods
+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),
+};

package/src/types.ts

@@ -0,0 +1,236 @@
+// Core type definitions — 100% Refine-compatible DataProvider + AuthProvider + Providers
+
+// ─── DataProvider ─────────────────────────────────────────────
+
+export interface Pagination {
+  current?: number;
+  pageSize?: number;
+  mode?: 'server' | 'client' | 'off';
+}
+
+export interface Sort {
+  field: string;
+  order: 'asc' | 'desc';
+}
+
+export interface Filter {
+  field: string;
+  operator: 'eq' | 'ne' | 'lt' | 'gt' | 'lte' | 'gte' | 'contains' | 'in' | 'null' | 'between';
+  value: unknown;
+}
+
+export interface GetListParams {
+  resource: string;
+  pagination?: Pagination;
+  sorters?: Sort[];
+  filters?: Filter[];
+  meta?: Record<string, unknown>;
+}
+
+export interface GetListResult<T = Record<string, unknown>> {
+  data: T[];
+  total: number;
+}
+
+export interface GetOneParams {
+  resource: string;
+  id: string | number;
+  meta?: Record<string, unknown>;
+}
+
+export interface GetOneResult<T = Record<string, unknown>> {
+  data: T;
+}
+
+export interface GetManyParams {
+  resource: string;
+  ids: (string | number)[];
+  meta?: Record<string, unknown>;
+}
+
+export interface GetManyResult<T = Record<string, unknown>> {
+  data: T[];
+}
+
+export interface CreateParams {
+  resource: string;
+  variables: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+
+export interface CreateResult<T = Record<string, unknown>> {
+  data: T;
+}
+
+export interface CreateManyParams {
+  resource: string;
+  variables: Record<string, unknown>[];
+  meta?: Record<string, unknown>;
+}
+
+export interface CreateManyResult<T = Record<string, unknown>> {
+  data: T[];
+}
+
+export interface UpdateParams {
+  resource: string;
+  id: string | number;
+  variables: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+
+export interface UpdateResult<T = Record<string, unknown>> {
+  data: T;
+}
+
+export interface UpdateManyParams {
+  resource: string;
+  ids: (string | number)[];
+  variables: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+
+export interface UpdateManyResult<T = Record<string, unknown>> {
+  data: T[];
+}
+
+export interface DeleteParams {
+  resource: string;
+  id: string | number;
+  variables?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+
+export interface DeleteResult<T = Record<string, unknown>> {
+  data: T;
+}
+
+export interface DeleteManyParams {
+  resource: string;
+  ids: (string | number)[];
+  variables?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+
+export interface DeleteManyResult<T = Record<string, unknown>> {
+  data: T[];
+}
+
+export interface CustomParams {
+  url: string;
+  method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+  payload?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  headers?: Record<string, string>;
+  sorters?: Sort[];
+  filters?: Filter[];
+  meta?: Record<string, unknown>;
+}
+
+export interface CustomResult<T = unknown> {
+  data: T;
+}
+
+export interface DataProvider {
+  // Required methods
+  getList: <T = Record<string, unknown>>(params: GetListParams) => Promise<GetListResult<T>>;
+  getOne: <T = Record<string, unknown>>(params: GetOneParams) => Promise<GetOneResult<T>>;
+  create: <T = Record<string, unknown>>(params: CreateParams) => Promise<CreateResult<T>>;
+  update: <T = Record<string, unknown>>(params: UpdateParams) => Promise<UpdateResult<T>>;
+  deleteOne: <T = Record<string, unknown>>(params: DeleteParams) => Promise<DeleteResult<T>>;
+  getApiUrl: () => string;
+
+  // Optional bulk methods
+  getMany?: <T = Record<string, unknown>>(params: GetManyParams) => Promise<GetManyResult<T>>;
+  createMany?: <T = Record<string, unknown>>(params: CreateManyParams) => Promise<CreateManyResult<T>>;
+  updateMany?: <T = Record<string, unknown>>(params: UpdateManyParams) => Promise<UpdateManyResult<T>>;
+  deleteMany?: <T = Record<string, unknown>>(params: DeleteManyParams) => Promise<DeleteManyResult<T>>;
+
+  // Optional custom method
+  custom?: <T = unknown>(params: CustomParams) => Promise<CustomResult<T>>;
+}
+
+// ─── AuthProvider ─────────────────────────────────────────────
+
+export interface Identity {
+  id?: string;
+  name?: string;
+  email?: string;
+  avatar?: string;
+  [key: string]: unknown;
+}
+
+export interface AuthActionResult {
+  success: boolean;
+  redirectTo?: string;
+  error?: { message: string; name?: string };
+}
+
+export interface CheckResult {
+  authenticated: boolean;
+  redirectTo?: string;
+  error?: { message: string; name?: string };
+  logout?: boolean;
+}
+
+export interface AuthProvider {
+  login: (params: Record<string, unknown>) => Promise<AuthActionResult>;
+  logout: (params?: Record<string, unknown>) => Promise<AuthActionResult>;
+  check: (params?: Record<string, unknown>) => Promise<CheckResult>;
+  getIdentity: () => Promise<Identity | null>;
+  getPermissions?: (params?: Record<string, unknown>) => Promise<unknown>;
+  register?: (params: Record<string, unknown>) => Promise<AuthActionResult>;
+  forgotPassword?: (params: Record<string, unknown>) => Promise<AuthActionResult>;
+  updatePassword?: (params: Record<string, unknown>) => Promise<AuthActionResult>;
+  onError?: (error: unknown) => Promise<{ redirectTo?: string; logout?: boolean }>;
+}
+
+// ─── NotificationProvider ─────────────────────────────────────
+
+export interface NotificationProvider {
+  open: (params: { type: 'success' | 'error' | 'warning' | 'info'; message: string; description?: string; key?: string }) => void;
+  close: (key: string) => void;
+}
+
+// ─── MutationMode ─────────────────────────────────────────────
+
+export type MutationMode = 'pessimistic' | 'optimistic' | 'undoable';
+
+// ─── ResourceDefinition ───────────────────────────────────────
+
+export interface ResourceDefinition {
+  name: string;
+  label: string;
+  icon?: string;
+  primaryKey?: string;
+  fields: FieldDefinition[];
+  defaultSort?: Sort;
+  pageSize?: number;
+  canCreate?: boolean;
+  canEdit?: boolean;
+  canDelete?: boolean;
+  canShow?: boolean;
+  meta?: Record<string, unknown>;
+}
+
+export interface FieldDefinition {
+  key: string;
+  label: string;
+  type: 'text' | 'number' | 'boolean' | 'date' | 'select' | 'multiselect' | 'tags'
+    | 'textarea' | 'richtext' | 'image' | 'images' | 'json' | 'relation' | 'color' | 'url' | 'email' | 'phone';
+  required?: boolean;
+  searchable?: boolean;
+  sortable?: boolean;
+  width?: string;
+  showInList?: boolean;
+  showInForm?: boolean;
+  showInCreate?: boolean;
+  showInEdit?: boolean;
+  showInShow?: boolean;
+  options?: { label: string; value: string | number }[];
+  defaultValue?: unknown;
+  // Relation support
+  resource?: string;       // related resource name
+  optionLabel?: string;    // field to use as label
+  optionValue?: string;    // field to use as value
+}

package/src/url-sync.ts

@@ -0,0 +1,55 @@
+// URL state sync — sync pagination/sort/filters with hash params
+
+export interface URLState {
+  page?: number;
+  pageSize?: number;
+  sortField?: string;
+  sortOrder?: 'asc' | 'desc';
+  search?: string;
+}
+
+export function readURLState(): URLState {
+  const hash = window.location.hash;
+  const queryIdx = hash.indexOf('?');
+  if (queryIdx === -1) return {};
+
+  const params = new URLSearchParams(hash.slice(queryIdx + 1));
+  const state: URLState = {};
+
+  const page = params.get('page');
+  if (page) state.page = parseInt(page, 10);
+
+  const pageSize = params.get('pageSize');
+  if (pageSize) state.pageSize = parseInt(pageSize, 10);
+
+  const sortField = params.get('sort');
+  if (sortField) state.sortField = sortField;
+
+  const sortOrder = params.get('order');
+  if (sortOrder === 'asc' || sortOrder === 'desc') state.sortOrder = sortOrder;
+
+  const search = params.get('q');
+  if (search) state.search = search;
+
+  return state;
+}
+
+export function writeURLState(state: URLState): void {
+  const hash = window.location.hash;
+  const pathIdx = hash.indexOf('?');
+  const basePath = pathIdx === -1 ? hash : hash.slice(0, pathIdx);
+
+  const params = new URLSearchParams();
+  if (state.page && state.page > 1) params.set('page', String(state.page));
+  if (state.pageSize && state.pageSize !== 10) params.set('pageSize', String(state.pageSize));
+  if (state.sortField) params.set('sort', state.sortField);
+  if (state.sortOrder) params.set('order', state.sortOrder);
+  if (state.search) params.set('q', state.search);
+
+  const qs = params.toString();
+  const newHash = qs ? `${basePath}?${qs}` : basePath;
+
+  if (window.location.hash !== newHash) {
+    history.replaceState(null, '', newHash);
+  }
+}