@svadmin/core 0.0.3 → 0.3.0

package/src/table-hooks.svelte.ts

@@ -0,0 +1,178 @@
+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 { UseListOptions } from './query-hooks.svelte';
+
+export type FilterSetMode = 'merge' | 'replace';
+
+export interface UseTableOptions<TQueryFnData extends BaseRecord = BaseRecord, TError = HttpError, TSearchVariables = Record<string, unknown>> extends Omit<UseListOptions<TQueryFnData, 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;
+}
+
+export function useTable<
+  TQueryFnData extends BaseRecord = BaseRecord,
+  TError = HttpError,
+  TSearchVariables = Record<string, unknown>
+>(options: UseTableOptions<TQueryFnData, TError, TSearchVariables> = {}) {
+  const parsed = useParsed();
+  const resource = options.resource ?? parsed.resource ?? '';
+  const { meta, syncWithLocation = false, dataProviderName, pagination: _p, sorters: _s, filters: _f, ...restOptions } = options;
+  
+  const paginationMode = options.pagination?.mode ?? 'server';
+  const sortersMode = options.sorters?.mode ?? 'server';
+  const filtersMode = options.filters?.mode ?? 'server';
+  const filterDefaultBehavior = options.filters?.defaultBehavior ?? 'replace';
+
+  const permanentSorters = options.sorters?.permanent ?? [];
+  const permanentFilters = options.filters?.permanent ?? [];
+
+  let initPagination = options.pagination ?? { current: 1, pageSize: 10 };
+  let initSorters = options.sorters?.initial ?? [];
+  let initFilters = options.filters?.initial ?? [];
+
+  if (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;
+    }
+  }
+
+  let pagination = $state<Pagination>(initPagination);
+  let currentSorters = $state<Sort[]>(initSorters);
+  let currentFilters = $state<Filter[]>(initFilters);
+
+  const effectiveSorters = $derived([...currentSorters, ...permanentSorters]);
+  const effectiveFilters = $derived([...currentFilters, ...permanentFilters]);
+
+  const querySorters = $derived(sortersMode === 'server' ? effectiveSorters : []);
+  const queryFilters = $derived(filtersMode === 'server' ? effectiveFilters : []);
+  const queryPagination = paginationMode === 'server'
+    ? pagination
+    : { current: 1, pageSize: 999999, mode: paginationMode as 'client' | 'off' };
+
+  const tableQueryInfo = useList<TQueryFnData, TError>({
+    resource,
+    pagination: queryPagination,
+    sorters: querySorters,
+    filters: queryFilters,
+    meta,
+    dataProviderName,
+    ...restOptions
+  });
+
+  const query = tableQueryInfo.query;
+  const overtime = tableQueryInfo.overtime;
+
+  function setSorters(newSorters: Sort[]) { currentSorters = newSorters; }
+  function setFilters(newFilters: Filter[], mode?: FilterSetMode) {
+    const behavior = mode ?? filterDefaultBehavior;
+    if (behavior === 'merge') {
+      const merged = [...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);
+        }
+      }
+      currentFilters = merged;
+    } else {
+      currentFilters = newFilters;
+    }
+    pagination = { ...pagination, current: 1 };
+  }
+
+  function setPage(page: number) { pagination = { ...pagination, current: page }; }
+  function setPageSize(size: number) { pagination = { ...pagination, pageSize: size, current: 1 }; }
+
+  if (syncWithLocation && typeof window !== 'undefined') {
+    $effect(() => {
+      writeURLState({
+        page: pagination.current,
+        pageSize: pagination.pageSize,
+        sortField: effectiveSorters[0]?.field,
+        sortOrder: effectiveSorters[0]?.order,
+        filters: effectiveFilters,
+      });
+    });
+  }
+
+  function createLinkForSyncWithLocation(): string {
+    const params = new URLSearchParams();
+    if (pagination.current) params.set('page', String(pagination.current));
+    if (pagination.pageSize) params.set('pageSize', String(pagination.pageSize));
+    if (effectiveSorters[0]) {
+      params.set('sortField', effectiveSorters[0].field);
+      params.set('sortOrder', effectiveSorters[0].order);
+    }
+    if (effectiveFilters.length > 0) {
+      params.set('filters', JSON.stringify(effectiveFilters));
+    }
+    return `?${params.toString()}`;
+  }
+
+  return {
+    query,
+    tableQuery: query,
+    get overtime() { return overtime; },
+    get pagination() { return pagination; },
+    get sorters() { return currentSorters; },
+    get filters() { return currentFilters; },
+    setSorters, setFilters, setPage, setPageSize,
+    setCurrentPage: setPage,
+    createLinkForSyncWithLocation,
+    get totalPages() {
+      // ts-expect-error reactive access
+      const total = (query as any).data?.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 clientData(): TQueryFnData[] {
+      if (paginationMode !== 'client') return [];
+      const allData = ((query as any).data?.data ?? []) as TQueryFnData[];
+      const start = ((pagination.current ?? 1) - 1) * (pagination.pageSize ?? 10);
+      const end = start + (pagination.pageSize ?? 10);
+      let sorted = [...allData];
+      const activeSorters = sortersMode === 'off' ? effectiveSorters : 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,12 +1,14 @@
 // Toast notification system — Svelte 5 runes-based
 
-export type ToastType = 'success' | 'error' | 'info' | 'warning';
+export type ToastType = 'success' | 'error' | 'info' | 'warning' | 'undoable';
 
 export interface Toast {
   id: number;
   type: ToastType;
   message: string;
   duration: number;
+  onUndo?: () => void;
+  onTimeout?: () => void;
 }
 
 let nextId = 0;
@@ -16,10 +18,10 @@ export function getToasts(): Toast[] {
   return toasts;
 }
 
-export function addToast(type: ToastType, message: string, duration = 3000): void {
+export function addToast(type: ToastType, message: string, duration = 3000, options?: { onUndo?: () => void, onTimeout?: () => void }): void {
   const id = nextId++;
-  toasts = [...toasts, { id, type, message, duration }];
-  if (duration > 0) {
+  toasts = [...toasts, { id, type, message, duration, ...options }];
+  if (duration > 0 && type !== 'undoable') {
     setTimeout(() => removeToast(id), duration);
   }
 }
@@ -34,4 +36,6 @@ export const toast = {
   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) => 
+    addToast('undoable', msg, duration, { onUndo, onTimeout }),
 };

package/src/types.ts

@@ -1,4 +1,31 @@
-// Core type definitions — 100% Refine-compatible DataProvider + AuthProvider + Providers
+// Core type definitions — DataProvider + AuthProvider + Providers
+
+// ─── HttpError ─────────────────────────────────────────────────
+
+export type ValidationErrors = Record<string, string | string[]>;
+
+export class HttpError extends Error {
+  statusCode: number;
+  errors?: ValidationErrors;
+
+  constructor(message: string, statusCode: number, errors?: ValidationErrors) {
+    super(message);
+    this.name = 'HttpError';
+    this.statusCode = statusCode;
+    this.errors = errors;
+  }
+}
+
+export class UndoError extends Error {
+  constructor() {
+    super('Mutation undone');
+    this.name = 'UndoError';
+  }
+}
+
+// ─── Base Types ───────────────────────────────────────────────
+
+export type BaseRecord = Record<string, unknown>;
 
 // ─── DataProvider ─────────────────────────────────────────────
 
@@ -13,12 +40,25 @@ export interface Sort {
   order: 'asc' | 'desc';
 }
 
+export type CrudOperator =
+  | 'eq' | 'ne' | 'lt' | 'gt' | 'lte' | 'gte'
+  | 'contains' | 'ncontains'
+  | 'startswith' | 'endswith'
+  | 'in' | 'nin'
+  | 'null' | 'nnull'
+  | 'between' | 'nbetween';
+
 export interface Filter {
   field: string;
-  operator: 'eq' | 'ne' | 'lt' | 'gt' | 'lte' | 'gte' | 'contains' | 'in' | 'null' | 'between';
+  operator: CrudOperator;
   value: unknown;
 }
 
+export interface LogicalFilter {
+  operator: 'or' | 'and';
+  value: Filter[];
+}
+
 export interface GetListParams {
   resource: string;
   pagination?: Pagination;
@@ -27,8 +67,8 @@ export interface GetListParams {
   meta?: Record<string, unknown>;
 }
 
-export interface GetListResult<T = Record<string, unknown>> {
-  data: T[];
+export interface GetListResult<TData extends BaseRecord = BaseRecord> {
+  data: TData[];
   total: number;
 }
 
@@ -38,8 +78,8 @@ export interface GetOneParams {
   meta?: Record<string, unknown>;
 }
 
-export interface GetOneResult<T = Record<string, unknown>> {
-  data: T;
+export interface GetOneResult<TData extends BaseRecord = BaseRecord> {
+  data: TData;
 }
 
 export interface GetManyParams {
@@ -48,78 +88,78 @@ export interface GetManyParams {
   meta?: Record<string, unknown>;
 }
 
-export interface GetManyResult<T = Record<string, unknown>> {
-  data: T[];
+export interface GetManyResult<TData extends BaseRecord = BaseRecord> {
+  data: TData[];
 }
 
-export interface CreateParams {
+export interface CreateParams<TVariables = unknown> {
   resource: string;
-  variables: Record<string, unknown>;
+  variables: TVariables;
   meta?: Record<string, unknown>;
 }
 
-export interface CreateResult<T = Record<string, unknown>> {
-  data: T;
+export interface CreateResult<TData extends BaseRecord = BaseRecord> {
+  data: TData;
 }
 
-export interface CreateManyParams {
+export interface CreateManyParams<TVariables = unknown> {
   resource: string;
-  variables: Record<string, unknown>[];
+  variables: TVariables[];
   meta?: Record<string, unknown>;
 }
 
-export interface CreateManyResult<T = Record<string, unknown>> {
-  data: T[];
+export interface CreateManyResult<TData extends BaseRecord = BaseRecord> {
+  data: TData[];
 }
 
-export interface UpdateParams {
+export interface UpdateParams<TVariables = unknown> {
   resource: string;
   id: string | number;
-  variables: Record<string, unknown>;
+  variables: TVariables;
   meta?: Record<string, unknown>;
 }
 
-export interface UpdateResult<T = Record<string, unknown>> {
-  data: T;
+export interface UpdateResult<TData extends BaseRecord = BaseRecord> {
+  data: TData;
 }
 
-export interface UpdateManyParams {
+export interface UpdateManyParams<TVariables = unknown> {
   resource: string;
   ids: (string | number)[];
-  variables: Record<string, unknown>;
+  variables: TVariables;
   meta?: Record<string, unknown>;
 }
 
-export interface UpdateManyResult<T = Record<string, unknown>> {
-  data: T[];
+export interface UpdateManyResult<TData extends BaseRecord = BaseRecord> {
+  data: TData[];
 }
 
-export interface DeleteParams {
+export interface DeleteParams<TVariables = unknown> {
   resource: string;
   id: string | number;
-  variables?: Record<string, unknown>;
+  variables?: TVariables;
   meta?: Record<string, unknown>;
 }
 
-export interface DeleteResult<T = Record<string, unknown>> {
-  data: T;
+export interface DeleteResult<TData extends BaseRecord = BaseRecord> {
+  data: TData;
 }
 
-export interface DeleteManyParams {
+export interface DeleteManyParams<TVariables = unknown> {
   resource: string;
   ids: (string | number)[];
-  variables?: Record<string, unknown>;
+  variables?: TVariables;
   meta?: Record<string, unknown>;
 }
 
-export interface DeleteManyResult<T = Record<string, unknown>> {
-  data: T[];
+export interface DeleteManyResult<TData extends BaseRecord = BaseRecord> {
+  data: TData[];
 }
 
-export interface CustomParams {
+export interface CustomParams<TVariables = unknown> {
   url: string;
   method: 'get' | 'post' | 'put' | 'patch' | 'delete';
-  payload?: Record<string, unknown>;
+  payload?: TVariables;
   query?: Record<string, unknown>;
   headers?: Record<string, string>;
   sorters?: Sort[];
@@ -127,27 +167,27 @@ export interface CustomParams {
   meta?: Record<string, unknown>;
 }
 
-export interface CustomResult<T = unknown> {
-  data: T;
+export interface CustomResult<TData = unknown> {
+  data: TData;
 }
 
 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>>;
+  getList: <TData extends BaseRecord = BaseRecord>(params: GetListParams) => Promise<GetListResult<TData>>;
+  getOne: <TData extends BaseRecord = BaseRecord>(params: GetOneParams) => Promise<GetOneResult<TData>>;
+  create: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: CreateParams<TVariables>) => Promise<CreateResult<TData>>;
+  update: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: UpdateParams<TVariables>) => Promise<UpdateResult<TData>>;
+  deleteOne: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: DeleteParams<TVariables>) => Promise<DeleteResult<TData>>;
   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>>;
+  getMany?: <TData extends BaseRecord = BaseRecord>(params: GetManyParams) => Promise<GetManyResult<TData>>;
+  createMany?: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: CreateManyParams<TVariables>) => Promise<CreateManyResult<TData>>;
+  updateMany?: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: UpdateManyParams<TVariables>) => Promise<UpdateManyResult<TData>>;
+  deleteMany?: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: DeleteManyParams<TVariables>) => Promise<DeleteManyResult<TData>>;
 
   // Optional custom method
-  custom?: <T = unknown>(params: CustomParams) => Promise<CustomResult<T>>;
+  custom?: <TData = unknown, TVariables = unknown>(params: CustomParams<TVariables>) => Promise<CustomResult<TData>>;
 }
 
 // ─── AuthProvider ─────────────────────────────────────────────
@@ -200,6 +240,8 @@ export type MutationMode = 'pessimistic' | 'optimistic' | 'undoable';
 
 export interface ResourceDefinition {
   name: string;
+  /** Unique identifier — use when multiple resources share the same `name` but target different DataProviders */
+  identifier?: string;
   label: string;
   icon?: string;
   primaryKey?: string;
@@ -210,7 +252,10 @@ export interface ResourceDefinition {
   canEdit?: boolean;
   canDelete?: boolean;
   canShow?: boolean;
-  meta?: Record<string, unknown>;
+  showInMenu?: boolean;
+  parentName?: string;
+  menuOrder?: number;
+  meta?: Record<string, unknown> & { dataProviderName?: string; parent?: string };
 }
 
 export interface FieldDefinition {
@@ -236,3 +281,35 @@ export interface FieldDefinition {
   // Validation
   validate?: (value: unknown) => string | null;
 }
+
+// ─── Resource Type Registry ───────────────────────────────────
+
+/**
+ * Extend this interface via declaration merging to register resource types.
+ * When registered, all hooks automatically infer data types from resource names.
+ *
+ * @example
+ * ```ts
+ * declare module '@svadmin/core' {
+ *   interface ResourceTypeMap {
+ *     users: { id: string; name: string; email: string }
+ *     posts: { id: string; title: string; content: string }
+ *   }
+ * }
+ *
+ * // Now hooks auto-infer:
+ * const list = useList({ resource: 'users' })
+ * // list.data → { id: string; name: string; email: string }[]
+ * ```
+ */
+export interface ResourceTypeMap {}
+
+/** When ResourceTypeMap is empty → string (backward compatible); otherwise → registered keys */
+export type KnownResources = keyof ResourceTypeMap extends never
+  ? string
+  : Extract<keyof ResourceTypeMap, string>
+
+/** Infer data type from resource name. Falls back to Record<string, unknown> for unregistered resources */
+export type InferData<R extends string> = R extends keyof ResourceTypeMap
+  ? ResourceTypeMap[R]
+  : Record<string, unknown>

package/src/unsaved-changes.svelte.ts

@@ -0,0 +1,62 @@
+// UnsavedChangesNotifier — warns user before leaving page with unsaved changes
+// Svelte 5 component using runes
+
+import { onDestroy, onMount } from 'svelte';
+
+let warnWhenUnsavedChanges = $state(false);
+
+/**
+ * Call this to mark the form as dirty (has unsaved changes).
+ * When set to true, navigating away or closing the tab will trigger a warning.
+ */
+export function setUnsavedChanges(dirty: boolean) {
+  warnWhenUnsavedChanges = dirty;
+}
+
+export function getUnsavedChanges(): boolean {
+  return warnWhenUnsavedChanges;
+}
+
+const beforeUnloadHandler = (e: BeforeUnloadEvent) => {
+  if (warnWhenUnsavedChanges) {
+    e.preventDefault();
+    // Modern browsers ignore custom messages but require returnValue to be set
+    e.returnValue = '';
+    return '';
+  }
+};
+
+/**
+ * Initialize the UnsavedChangesNotifier.
+ * Call this in your root layout or AdminApp component.
+ * It handles both browser tab close and in-app navigation.
+ */
+export function initUnsavedChangesNotifier() {
+  if (typeof window === 'undefined') return;
+
+  window.addEventListener('beforeunload', beforeUnloadHandler);
+
+  // For hash-based navigation, intercept hashchange
+  const hashChangeHandler = (e: HashChangeEvent) => {
+    if (warnWhenUnsavedChanges) {
+      const confirmed = confirm('You have unsaved changes. Are you sure you want to leave?');
+      if (!confirmed) {
+        e.preventDefault();
+        // Restore original hash
+        if (e.oldURL) {
+          const oldHash = new URL(e.oldURL).hash;
+          history.replaceState(null, '', oldHash || '#');
+        }
+      } else {
+        warnWhenUnsavedChanges = false;
+      }
+    }
+  };
+
+  window.addEventListener('hashchange', hashChangeHandler);
+
+  return () => {
+    window.removeEventListener('beforeunload', beforeUnloadHandler);
+    window.removeEventListener('hashchange', hashChangeHandler);
+  };
+}

package/src/url-sync.ts

@@ -1,14 +1,18 @@
 // URL state sync — sync pagination/sort/filters with hash params
 
+import type { Filter } from './types';
+
 export interface URLState {
   page?: number;
   pageSize?: number;
   sortField?: string;
   sortOrder?: 'asc' | 'desc';
   search?: string;
+  filters?: Filter[];
 }
 
 export function readURLState(): URLState {
+  if (typeof window === 'undefined') return {};
   const hash = window.location.hash;
   const queryIdx = hash.indexOf('?');
   if (queryIdx === -1) return {};
@@ -31,10 +35,18 @@ export function readURLState(): URLState {
   const search = params.get('q');
   if (search) state.search = search;
 
+  const filtersRaw = params.get('filters');
+  if (filtersRaw) {
+    try {
+      state.filters = JSON.parse(filtersRaw);
+    } catch { /* ignore invalid json */ }
+  }
+
   return state;
 }
 
 export function writeURLState(state: URLState): void {
+  if (typeof window === 'undefined') return;
   const hash = window.location.hash;
   const pathIdx = hash.indexOf('?');
   const basePath = pathIdx === -1 ? hash : hash.slice(0, pathIdx);
@@ -45,6 +57,9 @@ export function writeURLState(state: URLState): void {
   if (state.sortField) params.set('sort', state.sortField);
   if (state.sortOrder) params.set('order', state.sortOrder);
   if (state.search) params.set('q', state.search);
+  if (state.filters && state.filters.length > 0) {
+    params.set('filters', JSON.stringify(state.filters));
+  }
 
   const qs = params.toString();
   const newHash = qs ? `${basePath}?${qs}` : basePath;