@svadmin/core 0.30.0 → 0.32.0

package/src/types.ts

@@ -1,18 +1,40 @@
 // Core type definitions — DataProvider + AuthProvider + Providers
 
+import type { Component } from 'svelte';
+
 // ─── HttpError ─────────────────────────────────────────────────
 
 export type ValidationErrors = Record<string, string | string[]>;
 
+export interface HttpErrorOptions {
+  code?: string;
+  details?: unknown;
+  body?: unknown;
+  cause?: unknown;
+}
+
 export class HttpError extends Error {
   statusCode: number;
   errors?: ValidationErrors;
-
-  constructor(message: string, statusCode: number, errors?: ValidationErrors) {
-    super(message);
+  code?: string;
+  details?: unknown;
+  body?: unknown;
+  override cause?: unknown;
+
+  constructor(
+    message: string,
+    statusCode: number,
+    errors?: ValidationErrors,
+    options: HttpErrorOptions = {},
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
     this.name = 'HttpError';
     this.statusCode = statusCode;
     this.errors = errors;
+    this.code = options.code;
+    this.details = options.details;
+    this.body = options.body;
+    this.cause = options.cause;
   }
 }
 
@@ -72,6 +94,7 @@ export interface GetListParams {
 export interface GetListResult<TData extends BaseRecord = BaseRecord> {
   data: TData[];
   total: number;
+  [key: string]: unknown;
 }
 
 export interface GetOneParams {
@@ -315,6 +338,8 @@ export interface AuthProvider {
   register?: (params: Record<string, unknown>) => Promise<AuthActionResult>;
   forgotPassword?: (params: Record<string, unknown>) => Promise<AuthActionResult>;
   updatePassword?: (params: Record<string, unknown>) => Promise<AuthActionResult>;
+  /** Update current user's identity fields such as name or email. */
+  updateIdentity?: (params: Partial<Identity> & Record<string, unknown>) => Promise<AuthActionResult>;
   /** Update user profile (name, avatar, etc.) */
   updateProfile?: (params: { name?: string; avatar?: string | File; [key: string]: unknown }) => Promise<AuthActionResult>;
   /** Get list of system roles for RBAC mapping */
@@ -382,7 +407,7 @@ export interface MenuItem {
   /** Display label. Falls back to `t('menu.${name}')` if omitted */
   label?: string;
   /** Icon name string (maps to lucide icon set) or Svelte component */
-  icon?: string | any;
+  icon?: string | Component;
   /** Navigation path — omit for parent-only menu nodes */
   href?: string;
   /** Open in new tab (useful for external links) */

package/src/unsaved-changes.svelte.ts

@@ -1,8 +1,7 @@
-/* eslint-disable svelte/prefer-svelte-reactivity */
 // UnsavedChangesNotifier — guards against accidental navigation with dirty forms
 // Supports: browser tab close, hash-based SPA routing, and framework router interception
 
-import { t } from './i18n.svelte';
+import { useTranslation } from './i18n.svelte';
 import { syncGlobalPath } from './useParsed.svelte';
 
 let dirty = $state(false);
@@ -15,46 +14,12 @@ export function resetUnsavedChanges(): void {
   dirty = false;
   _unsavedChangesCleanup?.();
   _unsavedChangesCleanup = null;
-  __navigationGuard = null;
 }
 
 export function getUnsavedChanges(): boolean {
   return dirty;
 }
 
-/**
- * Navigation interceptor callback type.
- * Frameworks like SvelteKit can register a cancel function here.
- * Return `true` to allow navigation, `false` to block it.
- */
-interface 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.
  * 
@@ -82,6 +47,7 @@ export function initUnsavedChangesNotifier(options?: {
   beforeNavigate?: (callback: (nav: { cancel: () => void }) => void) => void;
 }) {
   if (typeof window === 'undefined') return;
+  const i18n = useTranslation();
   _unsavedChangesCleanup?.();
 
   const onBeforeUnload = (e: BeforeUnloadEvent) => {
@@ -94,7 +60,7 @@ export function initUnsavedChangesNotifier(options?: {
   if (options?.beforeNavigate) {
     options.beforeNavigate(({ cancel }) => {
       if (dirty) {
-        if (!confirm(t('common.unsavedChanges'))) {
+        if (!confirm(i18n.t('common.unsavedChanges'))) {
           cancel();
         } else {
           dirty = false;
@@ -105,7 +71,7 @@ export function initUnsavedChangesNotifier(options?: {
 
   const onHashChange = (e: HashChangeEvent) => {
     if (!dirty) return;
-    if (!confirm(t('common.unsavedChanges'))) {
+    if (!confirm(i18n.t('common.unsavedChanges'))) {
       if (e.oldURL) {
         history.replaceState(null, '', new URL(e.oldURL).hash || '#');
         syncGlobalPath();

package/src/url-sync.ts

@@ -1,7 +1,44 @@
 import type { Filter } from './types';
-import { getRouterProvider } from './context.svelte';
+import { captureAdminContext } from './context.svelte';
+import type { AdminContextAccessor } from './context.svelte';
 import { getAdminOptions } from './options.svelte';
 
+const CRUD_OPERATORS = new Set([
+  'eq', 'ne', 'lt', 'gt', 'lte', 'gte',
+  'contains', 'ncontains', 'startswith', 'endswith',
+  'in', 'nin', 'null', 'nnull', 'between', 'nbetween',
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isFilter(value: unknown, depth: number, budget: { remaining: number }): value is Filter {
+  if (depth > 20 || budget.remaining-- <= 0 || !isRecord(value)) return false;
+
+  if (typeof value.field === 'string') {
+    return value.field.trim().length > 0
+      && typeof value.operator === 'string'
+      && CRUD_OPERATORS.has(value.operator)
+      && 'value' in value;
+  }
+
+  return (value.operator === 'and' || value.operator === 'or')
+    && Array.isArray(value.value)
+    && value.value.every((entry) => isFilter(entry, depth + 1, budget));
+}
+
+function parseFilters(value: string): Filter[] | undefined {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!Array.isArray(parsed)) return undefined;
+    const budget = { remaining: 200 };
+    return parsed.every((entry) => isFilter(entry, 0, budget)) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export interface URLState {
   page?: number;
   pageSize?: number;
@@ -11,9 +48,9 @@ export interface URLState {
   filters?: Filter[];
 }
 
-export function readURLState(): URLState {
+export function readURLState(adminContext: AdminContextAccessor = captureAdminContext()): URLState {
   if (typeof window === 'undefined') return {};
-  const rp = getRouterProvider();
+  const rp = adminContext.routerProvider;
   if (!rp) return {};
 
   const { params } = rp.parse();
@@ -36,17 +73,19 @@ export function readURLState(): URLState {
 
   const filtersRaw = params['filters'];
   if (filtersRaw) {
-    try {
-      state.filters = JSON.parse(filtersRaw);
-    } catch { /* ignore invalid json */ }
+    const filters = parseFilters(filtersRaw);
+    if (filters) state.filters = filters;
   }
 
   return state;
 }
 
-export function writeURLState(state: URLState): void {
+export function writeURLState(
+  state: URLState,
+  adminContext: AdminContextAccessor = captureAdminContext(),
+): void {
   if (typeof window === 'undefined') return;
-  const rp = getRouterProvider();
+  const rp = adminContext.routerProvider;
   if (!rp) return;
 
   const current = rp.parse();

package/src/useCan.ts

@@ -8,6 +8,7 @@ export interface UseCanOptions {
   resource: string;
   action: Action;
   params?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
   queryOptions?: {
     enabled?: boolean;
     staleTime?: number;
@@ -34,8 +35,8 @@ export function useCan(options: () => UseCanOptions): UseCanResult {
   const query = createQuery<CanResult>(() => {
     const opts = options();
     return {
-      queryKey: ['useCan', opts.resource, opts.action, opts.params] as const,
-      queryFn: () => canAccessAsync(opts.resource, opts.action, opts.params),
+      queryKey: ['useCan', opts.resource, opts.action, opts.params, opts.meta] as const,
+      queryFn: () => canAccessAsync(opts.resource, opts.action, opts.params, opts.meta),
       enabled: opts.queryOptions?.enabled ?? true,
       staleTime: opts.queryOptions?.staleTime ?? 5 * 60 * 1000,
     };

package/src/useParsed.svelte.ts

@@ -1,34 +1,45 @@
-/* eslint-disable svelte/prefer-svelte-reactivity */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 // useParsed — parse current URL hash into structured route info
 
-import { currentPath, registerRouterSync } from './router';
-import { getResources } from './context.svelte';
+import { registerRouterSync } from './router';
+import { captureAdminContext } from './context.svelte';
 
 interface ParsedRoute {
   resource?: string;
   resourcePath?: string;
   action?: 'list' | 'create' | 'edit' | 'show' | 'clone';
   id?: string;
+  /** Query params parsed from the URL search string (e.g. ?page=2). */
   params: Record<string, string>;
+  /** Parent path params derived from nested routes (e.g. /teams/123/users -> teamId). */
+  parentParams: Record<string, string>;
 }
 
-let globalPath = $state('/');
+let routeVersion = $state(0);
 
 export function resetGlobalPath(): void {
-  globalPath = typeof window !== 'undefined' ? currentPath() : '/';
+  routeVersion++;
 }
 export function syncGlobalPath(): void {
-  if (typeof window !== 'undefined') globalPath = currentPath();
+  routeVersion++;
 }
+
+/** 简单的英文名词单数化，处理常见复数模式（-ies, -ses, -es, -s） */
+function singularize(word: string): string {
+  if (word.endsWith('ies') && word.length > 3) return word.slice(0, -3) + 'y';
+  if (word.endsWith('ses') && word.length > 3) return word.slice(0, -2);
+  if (word.endsWith('es') && word.length > 2) return word.slice(0, -2);
+  if (word.endsWith('s') && word.length > 1) return word.slice(0, -1);
+  return word;
+}
+
 registerRouterSync(syncGlobalPath);
 
 if (typeof window !== 'undefined') {
-  globalPath = currentPath();
   if (!(window as any).__svadminParsedInit) {
     (window as any).__svadminParsedInit = true;
-    window.addEventListener('hashchange', () => { globalPath = currentPath(); });
-    window.addEventListener('popstate', () => { globalPath = currentPath(); });
+    window.addEventListener('hashchange', syncGlobalPath);
+    window.addEventListener('popstate', syncGlobalPath);
   }
 }
 
@@ -41,13 +52,22 @@ if (typeof window !== 'undefined') {
  *   // parsed.resource === 'posts'
  *   // parsed.action === 'edit'
  *   // parsed.id === '123'
+ *   // parsed.params contains query params only
+ *   // parsed.parentParams contains nested route params such as teamId
  */
 export function useParsed(): ParsedRoute {
-  const resources = $derived((() => { try { return getResources(); } catch { return []; } })());
+  const adminContext = captureAdminContext();
+  const resources = $derived(adminContext.resources);
+  const activePath = $derived.by(() => {
+    // Any router navigation increments routeVersion. Each tree then asks its
+    // captured provider for its own path instead of consuming a global router.
+    void routeVersion;
+    return adminContext.currentPath();
+  });
 
   const parsed = $derived.by(() => {
-    const p = globalPath;
-    const result: ParsedRoute = { params: {} };
+    const p = activePath;
+    const result: ParsedRoute = { params: {}, parentParams: {} };
 
     // Parse query params from hash
     const [pathname, queryString] = p.split('?');
@@ -75,12 +95,15 @@ export function useParsed(): ParsedRoute {
       result.resource = segments[resourceIndex];
       result.resourcePath = segments.slice(0, resourceIndex + 1).join('/');
 
-      // Add parent path params based on `<parentResource>/<parentId>` structure
+      // Add parent path params based on `<parentResource>/<parentId>` structure.
+      // These are kept separate from query params so that downstream filter
+      // injection only applies to path-derived parent params, never to
+      // arbitrary query params like ?tenantId=1.
       for (let i = 0; i < resourceIndex; i += 2) {
         if (segments[i] && segments[i + 1]) {
           const parentName = segments[i];
-          const singular = parentName.endsWith('s') ? parentName.slice(0, -1) : parentName;
-          result.params[`${singular}Id`] = segments[i + 1];
+          const singular = singularize(parentName);
+          result.parentParams[`${singular}Id`] = segments[i + 1];
         }
       }
 
@@ -136,5 +159,6 @@ export function useParsed(): ParsedRoute {
     get action() { return parsed.action; },
     get id() { return parsed.id; },
     get params() { return parsed.params; },
+    get parentParams() { return parsed.parentParams; },
   };
 }

package/src/utility-hooks.svelte.ts

@@ -1,13 +1,14 @@
-/* eslint-disable svelte/prefer-svelte-reactivity */
-import { useForm, type UseFormOptions, type UseFormReturn } from './form-hooks.svelte';
+import { useForm, type UseFormOptions } from './form-hooks.svelte';
 import { useQueryClient } from '@tanstack/svelte-query';
 import { useParsed } from './useParsed.svelte';
-import { getResource, getResources } from './context.svelte';
+import { captureAdminContext } from './context.svelte';
 import { getAdminOptions } from './options.svelte';
 import { t } from './i18n.svelte';
 import type { BaseRecord, HttpError, Filter, KnownResources, ResourceDefinition } from './types';
-import { useList, type UseListOptions } from './query-hooks.svelte';
+import { useList } from './query-hooks.svelte';
 import { toast } from './toast.svelte';
+import type { UseSelectOptions } from './hooks.svelte';
+import { useSelect as useSelectImpl } from './hooks.svelte';
 
 // ─── useModal ─────────────────────────────────────────────────
 export function useModal(options?: { defaultVisible?: boolean }) {
@@ -87,11 +88,12 @@ export interface MenuConfig {
 }
 
 export function useMenu() {
+  const adminContext = captureAdminContext();
   const parsed = useParsed();
 
   const menuItems = $derived.by<MenuConfig[]>(() => {
     const adminOptions = getAdminOptions();
-    const resources = getResources();
+    const resources = adminContext.resources;
     let items: MenuConfig[] = resources
       .filter((r: ResourceDefinition) => r.showInMenu !== false)
       .map((r: ResourceDefinition): MenuConfig => ({
@@ -123,6 +125,7 @@ export interface BreadcrumbItem {
 }
 
 export function useBreadcrumb() {
+  const adminContext = captureAdminContext();
   const parsed = useParsed();
   
   const items = $derived.by<BreadcrumbItem[]>(() => {
@@ -130,7 +133,7 @@ export function useBreadcrumb() {
     if (!parsed.resource) return list;
 
     try {
-      const res = getResource(parsed.resource);
+      const res = adminContext.getResource(parsed.resource);
       const chain: { label: string; link: string; icon?: string }[] = [];
       let current: typeof res | undefined = res;
       const visited = new Set<string>();
@@ -138,7 +141,7 @@ export function useBreadcrumb() {
         if (visited.has(current.name)) break;
         visited.add(current.name);
         chain.unshift({ label: current.label || current.name, link: `/${current.name}`, icon: current.icon });
-        current = current.parentName ? getResource(current.parentName) : undefined;
+        current = current.parentName ? adminContext.getResource(current.parentName) : undefined;
       }
       list.push(...chain);
 
@@ -181,3 +184,112 @@ export function useRelation<TData extends BaseRecord = BaseRecord, TError = Http
 export function useNotification() {
   return { open: toast.info, success: toast.success, error: toast.error, warning: toast.warning };
 }
+
+// ─── Field-specific hooks (refine-compatible) ─────────────────────
+// useCheckboxGroup / useRadioGroup / useAutocomplete are convenience
+// wrappers around useSelect for common form field patterns.
+
+export interface UseCheckboxGroupOptions<TData extends BaseRecord = BaseRecord> extends Omit<UseSelectOptions<TData>, 'optionLabel' | 'optionValue' | 'defaultValue'> {
+  /** Field on the record used as the option label (default: 'title') */
+  optionLabel?: string | ((item: TData) => string);
+  /** Field on the record used as the checkbox value (default: 'id') */
+  optionValue?: string | ((item: TData) => string | number);
+  /** Currently selected values — controlled mode */
+  defaultValue?: (string | number)[];
+}
+
+/**
+ * useCheckboxGroup — multi-select field state backed by a resource query.
+ * Provides a list of checkbox options plus helpers to toggle individual values.
+ */
+export function useCheckboxGroup<TData extends BaseRecord = BaseRecord>(options: UseCheckboxGroupOptions<TData>) {
+  const select = useSelectImpl<TData>(options);
+  let selected = $state<(string | number)[]>(options.defaultValue ?? []);
+
+  function toggle(value: string | number) {
+    const idx = selected.findIndex(v => String(v) === String(value));
+    if (idx >= 0) {
+      selected = selected.filter(v => String(v) !== String(value));
+    } else {
+      selected = [...selected, value];
+    }
+  }
+
+  function isSelected(value: string | number): boolean {
+    return selected.some(v => String(v) === String(value));
+  }
+
+  return {
+    query: select.query,
+    get options() { return select.options; },
+    onSearchChange: select.onSearchChange,
+    get selected() { return selected; },
+    toggle,
+    isSelected,
+    setSelected: (values: (string | number)[]) => { selected = values; },
+  };
+}
+
+export interface UseRadioGroupOptions<TData extends BaseRecord = BaseRecord> extends Omit<UseSelectOptions<TData>, 'optionLabel' | 'optionValue' | 'defaultValue'> {
+  optionLabel?: string | ((item: TData) => string);
+  optionValue?: string | ((item: TData) => string | number);
+  defaultValue?: string | number;
+}
+
+/**
+ * useRadioGroup — single-select field state backed by a resource query.
+ * Provides a list of radio options plus a setter for the currently selected value.
+ */
+export function useRadioGroup<TData extends BaseRecord = BaseRecord>(options: UseRadioGroupOptions<TData>) {
+  const { defaultValue: _dv, ...selectOpts } = options;
+  // useSelect 的 defaultValue 是数组类型；透传单值以便远程选项回填当前已选值
+  const select = useSelectImpl<TData>({
+    ...selectOpts,
+    defaultValue: _dv !== undefined ? [_dv] : [],
+  });
+  let value = $state<string | number | undefined>(_dv);
+
+  return {
+    query: select.query,
+    get options() { return select.options; },
+    onSearchChange: select.onSearchChange,
+    get value() { return value; },
+    setValue: (v: string | number) => { value = v; },
+  };
+}
+
+export interface UseAutocompleteOptions<TData extends BaseRecord = BaseRecord> extends Omit<UseSelectOptions<TData>, 'onSearch' | 'defaultValue'> {
+  optionLabel?: string | ((item: TData) => string);
+  optionValue?: string | ((item: TData) => string | number);
+  /** Field name to search against (default: optionLabel) */
+  searchField?: string;
+  defaultValue?: string | number;
+}
+
+/**
+ * useAutocomplete — typeahead search field backed by a resource query.
+ * Builds a 'contains' filter on the search field and debounces input.
+ */
+export function useAutocomplete<TData extends BaseRecord = BaseRecord>(options: UseAutocompleteOptions<TData>) {
+  const { searchField, defaultValue: _dv, ...selectOpts } = options;
+  const labelField = typeof options.optionLabel === 'string' ? options.optionLabel : 'title';
+
+  const select = useSelectImpl<TData>({
+    ...selectOpts,
+    defaultValue: _dv !== undefined ? [_dv] : [],
+    onSearch: (term) => [{
+      field: searchField ?? labelField,
+      operator: 'contains' as const,
+      value: term,
+    }],
+  });
+  let value = $state<string | number | undefined>(_dv);
+
+  return {
+    query: select.query,
+    get options() { return select.options; },
+    onSearchChange: select.onSearchChange,
+    get value() { return value; },
+    setValue: (v: string | number) => { value = v; },
+  };
+}