@svadmin/core 0.0.3 → 0.3.0

package/src/form-hooks.svelte.ts

@@ -0,0 +1,266 @@
+import { useQueryClient } from '@tanstack/svelte-query';
+import { useParsed } from './useParsed';
+import { getAdminOptions } from './options';
+import { getDataProviderForResource } from './context';
+import { createQuery, createMutation } from '@tanstack/svelte-query';
+import { toast } from './toast.svelte';
+import { t } from './i18n.svelte';
+import { audit } from './audit';
+import { navigate } from './router';
+import { HttpError } from './types';
+import type { BaseRecord, MutationMode, KnownResources } from './types';
+
+export interface UseFormOptions<TQueryFnData extends BaseRecord = BaseRecord, TError = HttpError, TVariables = Record<string, unknown>, TData extends BaseRecord = TQueryFnData> {
+  resource?: KnownResources;
+  action?: 'create' | 'edit' | 'clone';
+  id?: string | number;
+  redirect?: 'list' | 'edit' | 'show' | false;
+  successNotification?: string | false;
+  errorNotification?: string | false;
+  dataProviderName?: string;
+  onMutationSuccess?: (data: unknown) => void;
+  onMutationError?: (error: Error) => void;
+  meta?: Record<string, unknown>;
+  queryMeta?: Record<string, unknown>;
+  mutationMeta?: Record<string, unknown>;
+  disableServerSideValidation?: boolean;
+  validate?: (values: TVariables) => Record<string, string> | null;
+  autoSave?: {
+    enabled: boolean;
+    debounce?: number;
+    onFinish?: (values: TVariables) => TVariables;
+    invalidateOnUnmount?: boolean;
+    invalidates?: string[];
+  };
+  mutationMode?: MutationMode;
+  undoableTimeout?: number;
+  invalidates?: string[] | false;
+  optimisticUpdateMap?: {
+    list?: boolean | ((previous: unknown, variables: TVariables, id?: string | number) => unknown);
+    detail?: boolean | ((previous: unknown, variables: TVariables, id?: string | number) => unknown);
+  };
+  queryOptions?: { staleTime?: number; enabled?: boolean };
+  createMutationOptions?: Record<string, unknown>;
+  updateMutationOptions?: Record<string, unknown>;
+  warnWhenUnsavedChanges?: boolean;
+}
+
+export type UseFormResult<TQueryFnData extends BaseRecord = BaseRecord, TError = HttpError, TVariables = Record<string, unknown>, TData extends BaseRecord = TQueryFnData> = {
+  readonly query: unknown;
+  readonly mutation: unknown;
+  readonly formLoading: boolean;
+  readonly errors: Record<string, string>;
+  setFieldError: (field: string, message: string) => void;
+  clearErrors: () => void;
+  clearFieldError: (field: string) => void;
+  onFinish: (values: TVariables, finishOptions?: { redirect?: 'list' | 'edit' | 'show' | false }) => Promise<void>;
+  onFinishAutoSave: (values: TVariables) => Promise<void>;
+  triggerAutoSave: (values: TVariables) => void;
+  readonly autoSaveStatus: 'idle' | 'saving' | 'saved' | 'error';
+  readonly resource: string;
+  readonly action: 'create' | 'edit' | 'clone';
+  readonly id: string | number | undefined;
+  setId: (newId: string | number) => void;
+  readonly mutationMode: MutationMode;
+  redirect: (to: 'list' | 'edit' | 'show' | false) => void;
+  readonly autoSaveProps: { status: 'idle' | 'loading' | 'success' | 'error'; data: unknown; error: unknown };
+};
+
+export function useForm<
+  TQueryFnData extends BaseRecord = BaseRecord,
+  TError = HttpError,
+  TVariables = Record<string, unknown>,
+  TData extends BaseRecord = TQueryFnData
+>(options: UseFormOptions<TQueryFnData, TError, TVariables, TData> = {}): UseFormResult<TQueryFnData, TError, TVariables, TData> {
+  const queryClient = useQueryClient();
+  const parsed = useParsed();
+  const adminOptions = getAdminOptions();
+  
+  const resource = options.resource ?? parsed.resource ?? '';
+  const action = options.action ?? (parsed.action === 'list' ? 'create' : parsed.action as 'create' | 'edit' | 'clone') ?? 'create';
+  let currentId = $state<string | number | undefined>(options.id ?? parsed.id);
+  
+  const {
+    redirect: redirectDefault = 'list',
+    successNotification, errorNotification,
+    onMutationSuccess, onMutationError,
+    meta: hookMeta, queryMeta: hookQueryMeta, mutationMeta: hookMutationMeta,
+    disableServerSideValidation, validate, autoSave,
+    mutationMode = adminOptions.mutationMode ?? 'pessimistic',
+    undoableTimeout = adminOptions.undoableTimeout ?? 5000,
+    dataProviderName, invalidates: invalidateScopes,
+    optimisticUpdateMap,
+    queryOptions,
+  } = options;
+
+  const provider = getDataProviderForResource(resource, dataProviderName);
+  const parsedMeta = typeof window !== 'undefined' ? Object.fromEntries(new URLSearchParams(window.location.search).entries()) : {};
+  const queryMeta = { ...parsedMeta, ...hookMeta, ...hookQueryMeta };
+  const mutationMeta = { ...parsedMeta, ...hookMeta, ...hookMutationMeta };
+
+  function setId(newId: string | number) { currentId = newId; }
+
+  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 runValidation(values: TVariables): boolean {
+    clearErrors();
+    if (validate) {
+      const result = validate(values);
+      if (result && Object.keys(result).length > 0) {
+        errors = result;
+        return false;
+      }
+    }
+    return true;
+  }
+
+  function handleHttpError(error: Error) {
+    if (error instanceof HttpError && error.errors && !disableServerSideValidation) {
+      for (const [field, messages] of Object.entries(error.errors)) {
+        const msg = Array.isArray(messages) ? messages[0] : messages;
+        setFieldError(field, msg);
+      }
+      if (errorNotification !== false) toast.error(errorNotification || error.message || t('common.operationFailed'));
+    } else {
+      if (errorNotification !== false) toast.error(errorNotification || t('common.operationFailed') + ': ' + error.message);
+    }
+  }
+
+  const query = (action === 'edit' || action === 'clone') && currentId != null
+    ? createQuery(() => ({
+        queryKey: [resource, 'one', currentId],
+        queryFn: async () => {
+          const result = await provider.getOne<TQueryFnData>({ resource, id: currentId!, meta: queryMeta });
+          return result.data;
+        },
+        enabled: (queryOptions?.enabled ?? true) && currentId != null,
+        staleTime: queryOptions?.staleTime,
+      }))
+    : null;
+
+  const createMut = createMutation(() => ({
+    ...options.createMutationOptions,
+    mutationFn: (variables: TVariables) => provider.create<TData, TVariables>({ resource, variables, meta: mutationMeta }),
+    onSuccess: (data: { data: TData }) => {
+      if (invalidateScopes !== false) queryClient.invalidateQueries({ queryKey: [resource] });
+      if (successNotification !== false) toast.success(successNotification || t('common.createSuccess'));
+      audit({ action: 'create', resource, recordId: String(data.data.id) });
+      onMutationSuccess?.(data);
+      if (redirectOverride !== false) doRedirect(redirectOverride ?? redirectDefault);
+    },
+    onError: (error: Error) => { handleHttpError(error); onMutationError?.(error); },
+  }));
+
+  const updateMut = createMutation(() => ({
+    ...options.updateMutationOptions,
+    mutationFn: (variables: TVariables) => provider.update<TData, TVariables>({ resource, id: currentId!, variables, meta: mutationMeta }),
+    onSuccess: (data: { data: TData }) => {
+      if (invalidateScopes !== false) queryClient.invalidateQueries({ queryKey: [resource] });
+      if (successNotification !== false) toast.success(successNotification || t('common.updateSuccess'));
+      audit({ action: 'update', resource, recordId: String(currentId) });
+      onMutationSuccess?.(data);
+      if (redirectOverride !== false) doRedirect(redirectOverride ?? redirectDefault);
+    },
+    onError: (error: Error) => { handleHttpError(error); onMutationError?.(error); },
+  }));
+
+  let redirectOverride: 'list' | 'edit' | 'show' | false | undefined;
+
+  function doRedirect(to: 'list' | 'edit' | 'show' | false) {
+    if (to === 'list') navigate(`/${resource}`);
+    else if (to === 'edit' && currentId) navigate(`/${resource}/edit/${currentId}`);
+    else if (to === 'show' && currentId) navigate(`/${resource}/show/${currentId}`);
+  }
+
+  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);
+  }
+
+  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);
+  }
+
+  let autoSaveStatus = $state<'idle' | 'saving' | 'saved' | 'error'>('idle');
+  let autoSaveTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function triggerAutoSave(values: TVariables) {
+    if (!autoSave?.enabled || action === 'create') return;
+    if (autoSaveTimer) clearTimeout(autoSaveTimer);
+
+    autoSaveTimer = setTimeout(async () => {
+      const finalValues = autoSave.onFinish ? autoSave.onFinish(values) : values;
+      autoSaveStatus = 'saving';
+      try {
+        await provider.update<TData, TVariables>({ resource, id: currentId!, variables: finalValues, meta: mutationMeta });
+        const scopes = autoSave.invalidates ?? ['resourceAll'];
+        for (const scope of scopes) {
+          if (scope === 'resourceAll') queryClient.invalidateQueries({ queryKey: [resource] });
+          else if (scope === 'detail' && currentId) queryClient.invalidateQueries({ queryKey: [resource, 'one', currentId] });
+          else if (scope === 'list') queryClient.invalidateQueries({ queryKey: [resource, 'list'] });
+        }
+        autoSaveStatus = 'saved';
+        lastAutoSaveData = undefined; // placeholder for returned data
+        lastAutoSaveError = null;
+        setTimeout(() => { autoSaveStatus = 'idle'; }, 2000);
+      } catch (e) {
+        autoSaveStatus = 'error';
+        lastAutoSaveError = e;
+      }
+    }, autoSave.debounce ?? 1000);
+  }
+
+  let lastAutoSaveData = $state<unknown>(null);
+  let lastAutoSaveError = $state<unknown>(null);
+
+  if (autoSave?.invalidateOnUnmount) {
+    $effect(() => {
+      return () => queryClient.invalidateQueries({ queryKey: [resource] });
+    });
+  }
+
+  // warnWhenUnsavedChanges
+  const shouldWarn = options.warnWhenUnsavedChanges ?? adminOptions.warnWhenUnsavedChanges;
+  if (shouldWarn && typeof window !== 'undefined') {
+    $effect(() => {
+      const handler = (e: BeforeUnloadEvent) => {
+        // Here we'd typically check a dirty state, but useForm itself doesn't track dirty fields.
+        // Usually the form library (svelte-forms etc) handles dirty state.
+        // Assuming we always warn if enabled for now.
+        e.preventDefault();
+        e.returnValue = '';
+      };
+      window.addEventListener('beforeunload', handler);
+      return () => window.removeEventListener('beforeunload', handler);
+    });
+  }
+
+  return {
+    query,
+    get formLoading() { return ((query as any)?.isLoading ?? false) || (createMut as any).isPending || (updateMut as any).isPending; },
+    mutation: action === 'edit' ? updateMut : createMut,
+    onFinish,
+    onFinishAutoSave,
+    get errors() { return errors; },
+    setFieldError, clearErrors, clearFieldError,
+    triggerAutoSave,
+    get autoSaveStatus() { return autoSaveStatus; },
+    resource, action,
+    get id() { return currentId; },
+    setId, mutationMode, redirect: doRedirect,
+    get autoSaveProps() {
+      return {
+        status: autoSaveStatus as 'idle' | 'loading' | 'success' | 'error',
+        data: lastAutoSaveData,
+        error: lastAutoSaveError,
+      };
+    },
+  };
+}

package/src/helpers.ts

@@ -0,0 +1,157 @@
+// Refine v5 compatible utility helpers
+
+import type { Filter, Sort, CrudOperator } from './types';
+import { t } from './i18n.svelte';
+import { getTextTransformers } from './options';
+
+// ─── Table Helpers ────────────────────────────────────────────
+
+/**
+ * Get the current filter value for a field from a filter array.
+ * Useful for setting default values in filter inputs.
+ */
+export function getDefaultFilter(
+  columnName: string,
+  filters?: Filter[],
+  operatorType: CrudOperator = 'eq',
+): unknown | undefined {
+  if (!filters) return undefined;
+  const filter = filters.find((f) => {
+    if ('field' in f) {
+      return f.field === columnName && f.operator === operatorType;
+    }
+    return false;
+  });
+  return filter && 'value' in filter ? filter.value : undefined;
+}
+
+/**
+ * Get the current sort order for a field from a sorter array.
+ * Returns 'asc', 'desc', or undefined.
+ */
+export function getDefaultSortOrder(
+  columnName: string,
+  sorters?: Sort[],
+): 'asc' | 'desc' | undefined {
+  if (!sorters) return undefined;
+  const sortItem = sorters.find((item) => item.field === columnName);
+  return sortItem?.order as 'asc' | 'desc' | undefined;
+}
+
+/**
+ * Merge two filter arrays, deduplicating by field+operator.
+ * Filters in `newFilters` take priority over `prevFilters`.
+ * `permanentFilter` items are always preserved.
+ * Filters with undefined values are removed from the result.
+ */
+export function unionFilters(
+  permanentFilter: Filter[],
+  newFilters: Filter[],
+  prevFilters: Filter[] = [],
+): Filter[] {
+  const compareFilters = (a: Filter, b: Filter): boolean => {
+    if ('field' in a && 'field' in b) {
+      return a.field === b.field && a.operator === b.operator;
+    }
+    return false;
+  };
+
+  // Start with previous filters
+  let result = [...prevFilters];
+
+  // Apply new filters (override previous by field+operator)
+  for (const newFilter of newFilters) {
+    const idx = result.findIndex((f) => compareFilters(f, newFilter));
+    if (idx >= 0) {
+      result[idx] = newFilter;
+    } else {
+      result.push(newFilter);
+    }
+  }
+
+  // Ensure permanent filters are always present
+  for (const perm of permanentFilter) {
+    const idx = result.findIndex((f) => compareFilters(f, perm));
+    if (idx >= 0) {
+      result[idx] = perm;
+    } else {
+      result.push(perm);
+    }
+  }
+
+  // Remove filters with undefined values
+  return result.filter((f) => !('value' in f && f.value === undefined));
+}
+
+/**
+ * Merge two sorter arrays, deduplicating by field.
+ * Sorters in `newSorters` take priority.
+ */
+export function unionSorters(
+  permanentSorters: Sort[],
+  newSorters: Sort[],
+): Sort[] {
+  const result = [...newSorters];
+
+  for (const perm of permanentSorters) {
+    if (!result.some((s) => s.field === perm.field)) {
+      result.push(perm);
+    }
+  }
+
+  return result;
+}
+
+// ─── Upload Helpers ───────────────────────────────────────────
+
+/**
+ * Convert a File (or file-like object) to a base64 data URL string.
+ * Useful for image uploads and previews.
+ */
+export function file2Base64(file: File | { uid?: string } & Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.readAsDataURL(file as Blob);
+    reader.addEventListener('load', () => {
+      resolve(reader.result as string);
+    });
+    reader.addEventListener('error', () => {
+      reject(reader.error);
+    });
+  });
+}
+
+// ─── Document Title Helper ────────────────────────────────────
+
+/**
+ * Generate a default document title for a resource page.
+ * e.g., "Edit Post #5 | Admin" or "Posts | Admin"
+ */
+export function generateDefaultDocumentTitle(options?: {
+  resource?: string;
+  action?: string;
+  id?: string | number;
+  suffix?: string;
+}): string {
+  const { resource, action, id, suffix = ' | Admin' } = options ?? {};
+  const transformers = getTextTransformers();
+
+  if (!resource) {
+    return t('documentTitle.default', {}) || `Admin${suffix}`;
+  }
+
+  const resourceLabel = transformers.humanize
+    ? transformers.humanize(resource)
+    : resource.charAt(0).toUpperCase() + resource.slice(1);
+
+  const actionPrefixes: Record<string, string> = {
+    create: `${t('common.create', {}) || 'Create'} `,
+    clone: `#${id ?? ''} ${t('common.clone', {}) || 'Clone'} `,
+    edit: `#${id ?? ''} ${t('common.edit', {}) || 'Edit'} `,
+    show: `#${id ?? ''} ${t('common.detail', {}) || 'Show'} `,
+    list: '',
+  };
+
+  const prefix = action ? (actionPrefixes[action] ?? '') : '';
+  return `${prefix}${resourceLabel}${suffix}`;
+}

package/src/hook-utils.svelte.ts

@@ -0,0 +1,121 @@
+// Hook Utilities — shared reactive helpers for all hooks
+// Uses Svelte 5 runes ($state, $effect) for automatic lifecycle management
+
+import { useQueryClient } from '@tanstack/svelte-query';
+import type { LiveProvider, LiveEvent, LiveMode } from './live';
+import { toast } from './toast.svelte';
+
+// ─── Overtime Tracker ───────────────────────────────────────────
+// Tracks elapsed time during loading, auto-cleans via $effect
+
+export interface OvertimeOptions {
+  interval?: number; // ms, default 1000
+  onInterval?: (elapsedTime: number) => void;
+}
+
+export interface OvertimeResult {
+  readonly elapsedTime: number;
+}
+
+export function createOvertimeTracker(
+  isLoadingFn: () => boolean,
+  options: OvertimeOptions = {},
+): OvertimeResult {
+  const { interval = 1000, onInterval } = options;
+  let elapsedTime = $state(0);
+
+  $effect(() => {
+    if (isLoadingFn()) {
+      elapsedTime = 0;
+      const timer = setInterval(() => {
+        elapsedTime += interval;
+        onInterval?.(elapsedTime);
+      }, interval);
+      return () => clearInterval(timer);
+    } else {
+      elapsedTime = 0;
+    }
+  });
+
+  return {
+    get elapsedTime() { return elapsedTime; },
+  };
+}
+
+// ─── Live Subscription ──────────────────────────────────────────
+// Auto-subscribes to realtime events, invalidates queries on 'auto' mode
+
+export interface LiveSubscriptionParams {
+  resource: string;
+  liveProvider?: LiveProvider;
+  liveMode?: LiveMode;
+  onLiveEvent?: (event: LiveEvent) => void;
+  liveParams?: Record<string, unknown>;
+  enabled?: boolean;
+}
+
+export function createLiveSubscription(params: LiveSubscriptionParams): void {
+  const {
+    resource,
+    liveProvider,
+    liveMode = 'off',
+    onLiveEvent,
+    enabled = true,
+  } = params;
+
+  if (!liveProvider || liveMode === 'off' || !enabled) return;
+
+  const queryClient = useQueryClient();
+
+  $effect(() => {
+    const unsubscribe = liveProvider.subscribe({
+      resource,
+      callback: (event: LiveEvent) => {
+        onLiveEvent?.(event);
+        if (liveMode === 'auto') {
+          queryClient.invalidateQueries({ queryKey: [resource] });
+        }
+      },
+    });
+    return unsubscribe;
+  });
+}
+
+// ─── Notification Helpers ───────────────────────────────────────
+
+export type NotificationConfig =
+  | string
+  | false
+  | ((data?: unknown, values?: unknown, resource?: string) => { message: string; description?: string; type?: 'success' | 'error' })
+  | undefined;
+
+export function fireSuccessNotification(
+  config: NotificationConfig,
+  defaultMessage: string,
+  data?: unknown,
+  values?: unknown,
+  resource?: string,
+): void {
+  if (config === false) return;
+  if (typeof config === 'function') {
+    const result = config(data, values, resource);
+    toast.success(result.message);
+    return;
+  }
+  toast.success(config || defaultMessage);
+}
+
+export function fireErrorNotification(
+  config: NotificationConfig,
+  defaultMessage: string,
+  error?: unknown,
+): void {
+  if (config === false) return;
+  if (typeof config === 'function') {
+    const result = config(error);
+    toast.error(result.message);
+    return;
+  }
+  const errMsg = error instanceof Error ? error.message : String(error ?? '');
+  toast.error(config || `${defaultMessage}${errMsg ? ': ' + errMsg : ''}`);
+}